Articraft

Generate articulated 3D objects from a text prompt or a reference image. Articraft asks a model to write Python with its 3D authoring SDK. It compiles the code, checks the result, and exports a posable USDZ file.

You need Python 3.11 or later, uv, and an OpenAI API key.

1. Install Articraft and its development tools:

   uv sync --group dev

2. Add your API key to .env:

   OPENAI_API_KEY=your_key_here

3. Generate an object:

   uv run articraft "a jet engine"

   Articraft stores the run in runs/.

4. Open the completed run:

   uv run articraft view runs/<run-id>

   Use the viewer to inspect each version and move its joints.

Pass one local image when you want Articraft to reconstruct an object:

uv run articraft --image reference.png "reconstruct this desk lamp"

OpenAI, Anthropic, and Gemini accept reference images. OpenRouter accepts text only.

Call generate() when your program can wait for the complete result:

import articraft

result = articraft.generate(
    "reconstruct this desk lamp",
    image="reference.png",
    on_event=print,
)

print(result.status)
print(result.artifact)

Use await articraft.generate_async(...) in an asynchronous application. You can pass the same options to both functions.

Install the optional simulation tools and run the default drop test:

uv sync --group sim
uv run articraft simulate runs/<run-id>

The simulator can also test sliding friction and released joints. Read the simulation guide for the commands and result definitions.

OpenAI is the default provider. You can also use Anthropic, Gemini, or OpenRouter.

Read the provider guide for API keys, models, and provider limits.

Run the recorded generation test and the static checks before you send a change:

uv run pytest -q  # includes live model calls; needs OPENAI_API_KEY in .env
uv run ruff check .

The recorded test does not call a paid model API. See the test guide for the other test lanes.

• SDK guide
• Provider guide
• Simulation guide
• Agent design
• Examples
• Release guide
• Repository guide

Articraft uses the Apache 2.0 License.

It is the supported successor to the original Articraft harness and its research paper.