Introduction
3D to Video turns a rough 3D animation into a finished-looking shot. Instead of hoping a text-to-video model picks the right camera angle, you decide the movement in a 3D tool, render it grey, and let the model paint over it using a frame you have already styled. The result keeps your timing and composition and takes its colour, light and materials from that frame.
Key features & highlights
The layout controls the motion
Our 3-second clay clip of a walking toy astronaut with a slowly orbiting camera came back 3.0 seconds long at 24 fps, with every stride and the camera arc where the layout put them. Output length always equals layout length, up to two minutes.
One painted frame sets the look
We restyled the first layout frame as a Martian plain at golden hour, and the whole clip followed: dusty red ground, low mesas, warm rim light and long shadows. Adding a restyled last frame as last_image_url kept a 4-second version consistent to the final frame.
Request parameters
| Parameter | Required | Description |
|---|---|---|
video_url | Yes | The layout: a grey or clay render of your 3D scene, MP4 or WebM, up to 120 seconds; 24 fps works best. It sets camera, motion, timing and aspect ratio. at least 1 characters |
image_url | Yes | The look: the layout's first frame restyled with an image model (colour, light, materials, setting). Do not send the grey frame itself. at least 1 characters |
last_image_url | No | Optional. The layout's last frame restyled in the same style, to keep the look steady in shots longer than about three seconds. at least 1 characters |
prompt | Yes | One or two sentences describing the finished shot, consistent with the look image. Leave out clay, 3D or layout. at least 1 characters · at most 2000 characters |
resolution | No | 720p or 1080p (default). The layout's aspect ratio is kept. |
seed | No | Optional integer to repeat a result. No effect on price. |
Pricing
Charged per second of layout video, rounded up, at least 3 and at most 120 seconds. The per-second rate depends on resolution, with 1080p above 720p. A last-frame look, the prompt and the seed do not change the price. Failed runs are not billed.
| Specification | Price |
|---|---|
| $0.048 / second |
| $0.12 / second |
Use cases
From previs to pitch
Block out a scene with placeholder models and a real camera move, then turn it into a styled clip for a pitch deck, storyboard review or social teaser. Nobody has to build materials, lighting rigs or a full environment before the idea has been approved.
One animation, many settings
Keep a single layout and change only the look image and the sentence. The same walking character or turning product can appear in a forest, a neon city at night or a painted cartoon world, with identical timing in every version so the clips cut together.
Prompt guide & pro tips
Prepare the look image carefully
Export the very first frame of the exact layout you send, restyle it with any image model, and keep the pose, framing and horizon where they are. The closer the look image lines up with the layout, the cleaner the edges and the steadier the result. Do not upload the untouched grey frame: the output would stay grey.
Keep the prompt short and visual
Write one or two sentences about the finished scene in plain words, for example "A small astronaut in a white spacesuit walks across a dusty red Martian plain at golden hour while the camera slowly circles." Describe what the viewer sees, and never mention clay, grey models, 3D or the layout itself.
Plan longer shots in pieces
For anything over about three seconds, restyle the last layout frame too and pass it as last_image_url. Shots longer than two minutes have to be split; render each part separately with the same look images and seed so the parts match.
API quick start
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "spicyapi/3d-to-video-v1/video-edit",
"input": {
"image_url": "https://example.com/reference.png",
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"resolution": "1080p",
"video_url": "https://example.com/reference.mp4"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
See the API reference for authentication, the complete schema, polling, and error handling.