Blender Python with Claude Code

scene.py · empty scene to MP4, all in code (tested on Blender 5.3)

# scene.py: build a small animated scene entirely in code and render it.
# usage:
#   blender -b -P scene.py -- --preview      # 3 key frames at 25% size, as PNG
#   blender -b -P scene.py -- --final        # every frame at full size, as MP4
import sys, math, os
import bpy

args = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else []
PREVIEW = "--preview" in args
OUT = os.path.abspath(os.path.join(os.path.dirname(__file__), "out"))

bpy.ops.wm.read_factory_settings(use_empty=True)  # start from an empty scene
scene = bpy.context.scene
scene.frame_start, scene.frame_end = 1, 72          # 3 seconds at 24 fps
scene.render.fps = 24

def material(name, rgb, rough=0.5, metal=0.0):
    m = bpy.data.materials.new(name)
    p = m.node_tree.nodes["Principled BSDF"]
    p.inputs["Base Color"].default_value = (*rgb, 1)
    p.inputs["Roughness"].default_value = rough
    p.inputs["Metallic"].default_value = metal
    return m

# ground and a bouncing ball, all generated in code
bpy.ops.mesh.primitive_plane_add(size=20)
bpy.context.object.data.materials.append(material("Ground", (0.08, 0.09, 0.12), rough=0.9))
bpy.ops.mesh.primitive_uv_sphere_add(radius=0.6, segments=64, ring_count=32)
ball = bpy.context.object
bpy.ops.object.shade_smooth()
ball.data.materials.append(material("Ball", (0.95, 0.45, 0.15), rough=0.25))

# keyframes: three bounces, squashed on contact
for f in range(scene.frame_start, scene.frame_end + 1):
    t = (f - 1) / 24
    phase = (t % 1.0)
    height = 4 * phase * (1 - phase) * 2.0          # parabola per bounce
    ball.location = (t * 1.2 - 1.8, 0, 0.6 + height)
    squash = 1 - 0.25 * max(0.0, 1 - height / 0.4)
    ball.scale = (1 / math.sqrt(squash), 1 / math.sqrt(squash), squash)
    ball.keyframe_insert("location", frame=f)
    ball.keyframe_insert("scale", frame=f)

# light, camera, world
bpy.ops.object.light_add(type="SUN", location=(4, -4, 8))
bpy.context.object.data.energy = 3.0
bpy.context.object.rotation_euler = (math.radians(50), 0, math.radians(35))
bpy.ops.object.camera_add(location=(0, -10, 2.4), rotation=(math.radians(84), 0, 0))
scene.camera = bpy.context.object
scene.world = bpy.data.worlds.new("World")
scene.world.node_tree.nodes["Background"].inputs["Color"].default_value = (0.02, 0.025, 0.035, 1)

# render settings
scene.render.engine = "BLENDER_EEVEE"
scene.render.resolution_x, scene.render.resolution_y = 1280, 720
scene.render.resolution_percentage = 25 if PREVIEW else 100

if PREVIEW:
    scene.render.image_settings.file_format = "PNG"
    for f in (1, 18, 36):
        scene.frame_set(f)
        scene.render.filepath = os.path.join(OUT, f"preview_{f:03d}.png")
        bpy.ops.render.render(write_still=True)
else:
    scene.render.image_settings.media_type = "VIDEO"
    scene.render.image_settings.file_format = "FFMPEG"
    scene.render.ffmpeg.format = "MPEG4"
    scene.render.ffmpeg.codec = "H264"
    scene.render.filepath = os.path.join(OUT, "ball_")
    bpy.ops.render.render(animation=True)

Terminal · preview, then final (tested on Blender 5.3, Apple M4)

# macOS path; on Linux use "blender", on Windows the full path to blender.exe
BLENDER=/Applications/Blender.app/Contents/MacOS/Blender

$BLENDER -b -P scene.py -- --preview   # 3 frames at 25% size -> out/preview_*.png  (~26 s)
$BLENDER -b -P scene.py -- --final     # 72 frames at 1280x720 -> out/ball_0001-0072.mp4  (77 s, EEVEE)

~/.claude/skills/blender-scene/SKILL.md (ours)

---
name: blender-scene
description: Build, preview and render Blender scenes and animations with Python from the command line. Use when the user asks for a 3D scene, model, animation or rendered video made in Blender.
---

# Blender scenes from the command line

Blender: /Applications/Blender.app/Contents/MacOS/Blender   (edit for your machine)

1. Never open the Blender window. Run: BLENDER -b -P scene.py -- <args>.
2. At the start of a session, print bpy.app.version and the available render
   engines; do not rely on memory for API names.
3. Start from bpy.ops.wm.read_factory_settings(use_empty=True). Generate all
   geometry, materials, keyframes, camera and lights in code. No downloaded
   models, textures or HDRIs unless the user supplies them.
4. Compute every keyframe from the frame number so the animation is
   deterministic. Write reusable generator functions before assembling.
5. Keep two modes: --preview renders 3-6 key frames at 25% size as PNG;
   --final renders the whole animation.
6. After every change, run --preview, open the PNGs, list what looks wrong
   (out of frame, clipping, flat light, stiff motion), fix, and repeat.
7. Before --final, measure seconds per frame on the preview and tell the user
   how long the full render will take.
8. Video in Blender 5.x: image_settings.media_type = "VIDEO", then
   file_format = "FFMPEG", ffmpeg.format = "MPEG4", ffmpeg.codec = "H264".

Prompt template · Blender shot (ours)

Make a [length]-second Blender shot at [1280x720, 24fps]: [subject],
[camera move], [light and time of day], [mood].
Follow the blender-scene skill: command line only, everything generated in
code, deterministic keyframes. Show me the --preview frames and what you
fixed before you run --final, and tell me the expected render time first.

cURL

curl https://api.apimodels.app/v1/messages \
  -H "x-api-key: $APIMODELS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-fable-5-2",
    "max_tokens": 64000,
    "messages": [{"role": "user", "content": "Write a Blender 5.3 Python script, run with blender -b -P, that builds a lighthouse at dusk entirely in code and renders 3 preview frames at 25% size."}]
  }'

Can Claude Code use Blender?

Claude Code can drive Blender by writing a Python script and running it with blender -b -P scene.py, which needs no window. It then opens the rendered PNG or MP4 files to check the result. A Blender MCP server is an alternative when you want it to operate a Blender window you are watching.

How do I render a Blender animation from the command line?

Run blender -b -P scene.py, and in the script set the frame range, resolution and output, then call bpy.ops.render.render(animation=True). In Blender 5.x, set the output media_type to VIDEO before choosing FFMPEG to get an MP4 directly. Our 72-frame 1280×720 test rendered in 77 seconds with EEVEE on an Apple M4.

Why does a Blender script from Claude fail with an attribute error?

The usual cause is a Blender API change between versions: engine identifiers, output settings and node options move from release to release. Have Claude print bpy.app.version and the available engine names first, and on Blender 5.x leave out Material.use_nodes and World.use_nodes, which are deprecated because node trees exist by default.

Which Claude model is best for Blender?

Claude Fable 5.2 handled the most demanding public Blender work, such as a photoreal pelican on a bicycle built over almost three hours in Claude Code. For simpler scenes and fix rounds, Opus 5.5 at $2.40 / $12 per million tokens on apimodels.app is half Fable 5.2’s price, and Sonnet 5.5 at $1.20 / $6 covers small changes.

How much does it cost to make a Blender animation with Claude?

A long photoreal run can use about a million output tokens: the published pelican session used about 1.1 million on Fable 5.2, roughly $26.40 of output at apimodels.app prices before input and cache reads. Simple scenes cost a small fraction of that, and moving fix rounds to Opus 5.5 halves the per-token price.