Video
Create and poll adult video tasks: text-to-video, image-to-video, 5-180 s, 480p-1080p, storyboard segments, explicit flag, edit mode and prices.
Video generation shares the authentication, uploads, callbacks and errors documented in the Overview.
Terms on this page. A video of 15s or less is a single clip. A longer video is a multi-shot video: the API renders each shot and stitches the shots together. The API lists the shots in a segments array, and one segment is one shot. The storyboard of a multi-shot video is the scene field. Most task calls return the task view.
Image to video
Animate your own image: any HTTPS URL, or a file from Upload a reference image.
- Pin it as the opening or closing frame: an
image_urlitem with"role": "first_frame"or"role": "last_frame". See Fields. - Use it as a reference image (no
role): the same person in a new composition. At most 9 image items per task, frames included. - Frames on each shot: on a multi-shot video, every shot in
segments(4–15s) can pin its ownfirst_frameandlast_frame. See Advanced mode. - A video is 5–180s, at 480p, 720p or 1080p. Images and frames do not change the price.
Guides: image-to-video, first and last frames and reference images for the same faces.
Create a video task
Create a task and reserve its price from your balance.
POST /api/v3/contents/generations/tasks
curl -s -X POST "$NURETA_URL/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer sk-..." \
-H "Content-Type: application/json" \
-d '{
"model": "seahorse-480p",
"content": [
{"type": "text", "text": "a seahorse dancing through neon waves"},
{"type": "image_url", "image_url": {"url": "https://example.com/start.jpg"}, "role": "first_frame"},
{"type": "image_url", "image_url": {"url": "https://example.com/end.jpg"}, "role": "last_frame"}
],
"ratio": "16:9",
"duration": 5,
"callback_url": "https://example.com/webhooks/nureta-developer"
}'
# => 201 {"id": "cgt-...", "status": "...", "prompt": "...", "media": [...], "mode": "auto", "step": {...}, ...}Fields
| Field | Required | Notes |
|---|---|---|
model | yes | seahorse-480p, seahorse-720p, or seahorse-1080p. Or a direct Seedance model: seedance2.0-fast or seedance2.0-pro. See Models & pricing. |
resolution | no | Direct Seedance models: 480p or 720p (default). The price follows the resolution. On a seahorse-<res> model, the resolution is in the model id. Omit resolution or send the same value. Another value returns 400 InvalidParameter. |
content | yes (optional with segments) | A non-empty array. Include exactly one text item. With segments, you can omit the text item or all of content. The prompt is then the segment scripts joined with ". ". |
content[].type | yes | text, image_url, library_item, or audio_url. |
image_url.url | for image_url | An HTTPS or HTTP asset URL that Seahorse reads. Use your own hosted URL or the assetUrl from Upload a reference image. At most 9 image items, library_item items included. |
library_item.id | for library_item | The id of one of your saved library items: chr_... (a character) or bg_... (a background). See Library items in a video. |
person | with cast | On a face image_url or a character library_item: the cast id (p1–p8) of the person in the photo. See Cast. |
cast | no | The people of the video, with ids. See Cast. Not with last_frame. With first_frame only together with photo_split_id. |
photo_split | no | "auto" or "off". auto splits your photos in the job: a photo with several people becomes one photo per person, a room becomes the background, and a photo of a finished scene becomes the opening frame. off uses your photos as they are. If you send nothing, your key's setting applies. Not on a direct Seedance model. See Photo split. |
photo_split_id | no | The 32-character id of a split you reviewed. Lets a cast use the split's opening frame as first_frame, and lets the cast have up to 4 people. Not on a direct Seedance model. |
role | no | Set background on an image_url item to use it as the place, not as a person (at most one background per video). With cast, set pose on an image_url item to use it as a pose reference. Set first_frame or last_frame on one image_url item to pin the opening or closing frame. Send a frame or reference media, not both. With a frame, that clip renders frame-conditioned. It ignores all reference media (role-less images and the audio item) and preset assets. On a multi-shot video, first_frame applies only to the first shot and last_frame only to the last shot. Only those shots drop their references. |
audio_url.url | for audio_url | An HTTPS or HTTP asset URL of an MP3 or WAV file. At most one audio item. Another format (for example .m4a, .aac, .mp4, or a server Content-Type such as audio/mp4 when the URL has no extension) returns 400 InvalidParameter before you are charged. |
ratio | no | Default 16:9. Allowed: 16:9, 9:16, 4:3, 3:4, 1:1, 21:9, adaptive. |
duration | no | Default 5. A single clip is 5, 8, 10, 12, or 15s. A longer video renders as a stitched multi-shot video of any integer from 16 to 180s (3 min). Direct Seedance models are single-clip only (max 15s). |
generate_audio | no | Default true. |
music | no | Background music: none (default, natural sound only), ambient, romantic or upbeat. Instrumental only. Another value returns 400 InvalidParameter. A clip may be delivered without music when the provider's copyright check fails its audio. |
music_note | no | Your own words for the background music, for example "slow jazz piano, rainy night". Sets music on by itself. At most 60 characters ({ and } count as spaces, whitespace collapsed). Instrumental only, and no real songs, artists or soundtracks by name. A note that names one returns 400 InvalidParameter (music_note refused: copyright) and a note that asks for singing or lyrics returns 400 InvalidParameter (music_note refused: vocals), before you are charged. In the rare case the name check is unavailable at create, a name found later fails the task with music_refused and refunds it. "No vocals" is fine. |
mode | no | Default auto (fully automated). Set edit to get a storyboard draft that you can edit before the render. See Storyboard modes. Video only, >15s. |
segments | no | Advanced mode: your own storyboard, as an array of shots. The shots must total 16–180s, and that total becomes the video duration. Video only. See Advanced mode for the shot fields, including chain_from_previous. |
auto_chain | no | Default false. true turns on auto chaining: smoother joins between the shots, and a longer render. Video only, >15s (or segments), seahorse-* models. On a single clip or a direct Seedance model it returns 400 InvalidParameter. No extra charge. |
callback_url | no | An HTTPS endpoint. The API POSTs the terminal task response to it. See Callback webhook. |
callback_secret | no | An 8–256 character shared secret that signs the callback body. Requires callback_url. |
Response
201 with the full task view, the same shape as GET.
Library items in a video
A saved library item is a reference image that you name by its id. A character is one person in the video. A background is the place. A video takes at most one background: a background library_item or an image_url with "role": "background".
curl -s -X POST "$NURETA_URL/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer sk-..." \
-H "Content-Type: application/json" \
-d '{
"model": "seahorse-480p",
"content": [
{"type": "text", "text": "She waits by the window, rain outside."},
{"type": "library_item", "library_item": {"id": "chr_..."}},
{"type": "library_item", "library_item": {"id": "bg_..."}}
],
"duration": 30
}'| You send | Single clip (≤15 s) | Multi-shot video | Storyboard edit (/plan, /plan/structured) |
|---|---|---|---|
A character (chr_...) | A reference image of a person. It counts toward the 9 images. | The same. | Continuity storyboard: bible.cast.<name>.photo takes library:chr_.... |
A background (bg_...) | A reference image of the place (no face). | The same. | segments[].background_image (older storyboards) and bible.locations.<id>.photo take library:bg_.... |
An image_url with role: "background" | The same as a background item. | The same. | Those fields take the image URL. |
Rules:
- Use your own items only. A deleted item, or an id of another account, returns
404 library_item_not_foundbefore anything is charged. - A character where a background goes, or the reverse, returns
422 library_kind_mismatch. - First and last frames do not take library items. The direct Seedance models do not take them either (
422 library_ref_unsupported). - Send the id, never the link of a library image: a library image link returns
403 MediaNotOwned. One exception: a storyboard edit may send back a link that the draft'sscenealready holds. - The task view lists an item in
mediaaslibrary:chr_...orlibrary:bg_.... - A background that shows a person can be refused by the provider's real-person check. On a multi-shot video, the API then uses a new background without people, or none. On a single clip, the task fails and is refunded.
Cast
Name the people of a video in a top-level cast. Each person has an id, a sex, and an optional name, looks and outfit. A photo of a person names its person with person. Photos are optional: one photo for the whole cast is enough, and a POV or solo video needs no face photo. The video then keeps each person's identity, and the task view tells you who is in each shot. A request without cast works as before.
| Field | Required | Notes |
|---|---|---|
cast.members | yes, with cast | At least 1 person. How many people, and which mixes of women and men, depend on your account. A cast has at most 3 people, and one clip shows at most 3. See Cast limits. |
members[].id | yes | p1 to p8, each id once. content[].person and cast.camera use it. |
members[].sex | yes | female or male. |
members[].name | no | 1–40 letters. After the first letter, spaces and . - ' ’ · ・ are allowed. No digits, @ # : " or new lines. Each name once (case does not matter). ’ becomes '. Omit the name and the API gives the person a label such as Woman A. You cannot send such a label yourself. |
members[].looks | no | Up to 120 characters, for example "freckles, short red hair". |
members[].outfit | no | Up to 120 characters. |
cast.camera | no | The id of the person whose eyes the camera is (point of view, POV). That person is not seen. Usually omit it: the API reads POV from the prompt ("POV: she rides me"). When the viewer is one of your people, that person becomes the camera. When the viewer is not in the cast, the API adds them (the next free id, generated: true). Either way camera is set to that id. Without a POV prompt there is no POV. |
content[].person | with cast, on every person photo | On an image_url with no role, or a character library_item: the id of the person in the photo. At most one photo per person. A person without a photo is fine: the API makes the person from sex, looks and outfit. |
role: "pose" | no | On an image_url, with cast only: a pose or framing reference. It is not a person and not the place, and it takes no person. |
A photo with no face. A person's photo does not have to show a face, for example a body from behind. The API then uses the photo as a reference for the body and pose, and makes that person's face, as for a person without a photo. The task view's input_warnings then has cast_photo_no_face. Such a photo is not refused when you submit it. But if the photo cannot be prepared for the video, the task can still fail with input_media_no_face. A photo with two or more faces is refused (input_media_many_faces).
POV. Write POV in the prompt ("POV: she rides me"). The shots are then filmed from the viewer's eyes, and the viewer is not seen. You do not need to set cast.camera. The viewer can be one of your people or someone the API adds. A face photo of the viewer is not used.
Rules. Each of these returns 400 InvalidParameter before anything is charged:
- With
cast, every person photo (animage_urlwith no role, or a characterlibrary_item) has aperson, and a person has at most one photo. - A person photo is your own: the
assetUrlof an upload from your account, or a saved library character. Any other link is refused (another account's upload:403 MediaNotOwned). - The
cast.cameraperson has no photo (nopersonthat names the camera). - With
cast, each image is given once: the same URL (query and fragment do not count) or the same library item twice is refused. - A background (
role: "background"or abg_...item), a pose, or a frame has noperson. castcannot be used withlast_frame, also not on asegments[]item or in a storyboard edit (a frame drops every reference image).castwithfirst_frameneeds thephoto_split_idof the split whose opening frame it is. Asegments[]item takes no frame with acast.- A character
library_itemhas the samesexas its person. personorrole: "pose"withoutcast.caston a direct Seedance model.
Cast limits
The cast limit and the allowed mixes of women and men depend on your account. A mix is one F per woman, then one M per man: two women and one man is FFM. A cast outside your account's limits is refused before anything is charged:
Status and error.code | Meaning |
|---|---|
400 cast_disabled | Casts are not available for your account. Send the request without cast. |
400 cast_too_large | The cast has more people than your account allows. error.max_people is the limit. |
400 cast_too_large with error.reason: "in_clip" | The video is one clip, and the cast has more people in frame than one clip can show. error.max_in_clip is the limit. See People in one clip. |
400 cast_combo_not_allowed | This mix of women and men is not available for your account. error.combo is your mix, error.allowed_combos the mixes you can use. |
503 cast_unavailable | The cast limits cannot be checked right now. Try again in a minute, or send the request without cast. Nothing is charged. |
A storyboard edit of a cast task (a bible.cast patch) also may not take the cast over the limit (400 InvalidParameter).
Photo split
With photo_split_id, a cast can have up to 4 people, if your account's split limits allow the mix. Without it the limit is 3. A video that starts from a split's opening frame renders its clips one after the other, so it takes longer.
A job whose photos were split adds these fields to its status and callback:
| Field | Meaning |
|---|---|
photo_split | The split: status, people (each with id, name, sex, crop_url, and drawn: true when the person has no crop and is drawn from the text), background.plate_url, opening_frame.url, bystander_count (people in the photos who are not in the video), and warnings. All links are HTTPS. |
cast | The people the split made, when the request had no cast. |
input_warnings | photo_split_failed, photo_split_crop_refused, photo_split_person_drawn, photo_split_plate_failed, photo_split_cast_capped, or photo_split_photo_kept (a face photo the split did not use, kept as a reference). The job goes on with your photos as sent, or with the people it could split. |
People in one clip
One clip shows at most 3 people in frame. The cast.camera person is not in frame and does not count. A video of 15 seconds or less without segments is one clip. For a bigger cast, use a longer duration: the API then puts the people in different shots.
- One clip: a cast with more people in frame than one clip can show returns
400 cast_too_largewitherror.reason: "in_clip"anderror.max_in_clip. Nothing is charged. - A longer video: the task fails with
error.codecast_too_largewhen the API cannot split the people across shots. The price is refunded. Try again, or use fewer people.
The 9-image limit stays: photos, backgrounds, poses and library items count together.
curl -s -X POST "$NURETA_URL/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer sk-..." \
-H "Content-Type: application/json" \
-d '{
"model": "seahorse-720p",
"content": [
{"type": "text", "text": "Mia and Yuna share a drink on a rooftop at sunset, then dance."},
{"type": "image_url", "image_url": {"url": "<assetUrl of your mia.jpg upload>"}, "person": "p1"},
{"type": "image_url", "image_url": {"url": "<assetUrl of your yuna.jpg upload>"}, "person": "p2"},
{"type": "image_url", "image_url": {"url": "https://example.com/rooftop.jpg"}, "role": "background"}
],
"cast": {
"members": [
{"id": "p1", "sex": "female", "name": "Mia", "outfit": "red silk dress"},
{"id": "p2", "sex": "female", "name": "Yuna", "looks": "short black hair"}
]
},
"duration": 30
}'A task with a cast adds these fields to the task view:
| Field | Meaning |
|---|---|
cast | Your cast, plus the POV person the API added when the prompt asks for POV and cast.camera is not set. Once the API knows the final names, each member also has its final name and generated (true when the API made the name). |
segment_people | The people in each shot, as {"0": ["p1", "p2"], "1": ["p1"]} (shot index from 0, then cast ids). |
input_warnings | Codes for parts of the prompt that the cast overrides: cast_story_extra_people (the prompt has more people than the cast; no person is added), cast_story_sex_mismatch (the prompt gives a person another sex than the cast), pov_no_camera (the prompt asks for POV, cast.camera is not set, and the API could not add the POV person), cast_photo_no_face (a person's photo shows no face: it is used for the body, and the face is made; see Cast). |
error.person | On a failed task: the id of the person whose photo caused the error. |
A cast task can fail with these error.code values. The price is refunded:
error.code | Meaning |
|---|---|
cast_disabled | Casts are not available for your account. Send the request without cast. |
cast_invalid | A cast field or a person is not valid. |
cast_too_large | The cast has more people than your account allows (for example, the limit changed after the task was created). Or the cast has more people in frame than one clip can show, and they could not be split across shots. See People in one clip. |
cast_combo_not_allowed | This mix of women and men is not available. Change the cast. |
cast_text_rejected | The content policy blocked a name, looks or outfit. |
input_media_no_face | The face in a person's photo could not be found while the video was made. A photo with no face at all is not refused when you submit it, but it fails with this code if it cannot be prepared (see Cast). |
input_media_many_faces | A person's photo shows more than one face. Use a photo of that person alone. |
Retrieve a video task
Get the current state of one task.
GET /api/v3/contents/generations/tasks/:id
curl -s "$NURETA_URL/api/v3/contents/generations/tasks/cgt-..." \
-H "Authorization: Bearer sk-..."Poll until status is succeeded, failed, cancelled, or planned. planned is an edit-mode draft that waits for you (see Storyboard modes).
On success, the response carries content.video_url. On failure, it carries an error, and the API issues a refund automatically.
The task view
Create, GET, list, and the storyboard calls all return the task view.
| Field | Type or values | Meaning |
|---|---|---|
id | string | The task id. |
model | string | The model. |
status | queued, running, planned, succeeded, failed, or cancelled | The task status. |
resolution | string | The resolution. |
ratio | string | The aspect ratio. |
duration | number | The video duration in seconds. |
created_at, updated_at | integer (Unix seconds) | When the task was created and last updated. |
step | object | Progress. See Progress (step). |
usage | object | price_usd and refunded. Also rerenders[] once a re-render ran. |
prompt | string | Your prompt. |
media | array | Your media, as [{url, type}]. type is Image or Audio. An item also has person or role (pose) when you sent one. |
cast, segment_people, input_warnings | object, object, array | Only on a task with a cast. See Cast. |
first_frame, last_frame | string | Your pinned frames. Only when set. |
mode | auto or edit | On every video task. |
scene | object | The storyboard. Only on a storyboard task. |
content | object | The result. Only when succeeded, and not after the video expired. |
error | object | The failure. Only when failed. |
expires_at | integer (Unix seconds) | When the video expires: 60 days after created_at. After that no response carries its links. |
expired | boolean | true after expires_at. The task has no content, and every media link in it is null. Re-render calls return 410 video_expired. |
rerender | object or null | GET only, when the video has re-render runs. The open run, or null. |
rerenders[] | array | GET only, when the video has re-render runs. Every run, in the full run shape. |
Progress (step)
Every video task response carries a step object with the current execution phase. Use it to show real progress while status is queued, running, or planned. Image tasks are a single step, so poll status for them.
"step": { "code": "rendering", "done": 3, "total": 5 }code is a stable machine string:
code | Mode | Meaning |
|---|---|---|
queued | all | Queued. |
generating_script | all | Generating the script. |
generating_visuals | all | Generating the visuals. |
pending_rendering | edit only | The draft is parked and waits for your render. |
rendering | all | Rendering. done and total appear only in this phase: clips completed and total clips. |
stitching | all | Stitching the shots. |
reexpanding | edit only | A structured re-expansion runs. |
reexpand_failed | edit only | The last re-expansion failed. Edit again before you render. |
done, failed, cancelled | all | Terminal codes. They track status. |
A single clip (15s or less, auto mode) and a direct Seedance task report only queued, rendering, and the terminal codes. Their rendering step has no done or total. generating_script, generating_visuals, stitching, and done/total appear only on multi-shot videos.
Map the codes to your own labels — the API never sends display text.
The step lags the true phase by up to ~30s, because a background poll refreshes it.
List video tasks
List your video tasks, newest first.
GET /api/v3/contents/generations/tasks?limit=20&offset=0
curl -s "$NURETA_URL/api/v3/contents/generations/tasks?limit=50&offset=50" \
-H "Authorization: Bearer sk-..."| Parameter | Values | Meaning |
|---|---|---|
limit | 1–100, default 20 | Page size. A value out of range is clamped. |
offset | integer | The number of tasks to skip. |
The response is { items, total }. items are task views. total counts all your video tasks.
Items do not include re-render runs (rerender, rerenders, usage.rerenders). GET one task to see them.
Delete a video task
Delete a finished task.
DELETE /api/v3/contents/generations/tasks/:id
curl -s -X DELETE "$NURETA_URL/api/v3/contents/generations/tasks/cgt-..." \
-H "Authorization: Bearer sk-..."A finished task is succeeded, failed, or cancelled. The call returns 200 {}. After that, the task no longer appears in GET or the list.
If a re-render of the video runs, the call stops it first. This happens even when the delete then fails (for example with 429). The shots not yet sent to render are refunded.
| Status | Meaning |
|---|---|
409 Conflict | The task is not finished. For a parked draft (planned), cancel it first. You can delete a running task when it finishes. |
409 | The running re-render could not be stopped. Try again shortly. |
404 NotFound | The task id is unknown, or it is an image or script task id. |
429 RateLimitExceeded | Your account already deleted 10 tasks in the last minute. All task kinds count. |
Data retention
| Data | Deleted |
|---|---|
| Copies we make from your reference photos (face-processed copies and the copies at our video provider) | When the re-render window ends: 3 days after the video is delivered. 72 hours after the task if it delivers nothing. Deleting the task deletes them at once. |
Files you uploaded (each assetUrl) | 3 days after the video that uses them is delivered, and 1 hour more so that a re-render started at the end can finish. While a task that uses a file is running, is a parked draft, or re-renders, the file is kept. 72 hours after upload if no delivered video uses it (a failed or cancelled task does not keep it). Deleting the task deletes them at once, unless another of your tasks still uses them. Deleting your account deletes them at once. |
| The video, its versions, poster and preview | Viewable for 60 days after the task was created. After that the task shows expired: true with no links. Deleted 80 days after the task was created, or at once when you delete the task. The task keeps its price and refund fields. Failed and cancelled tasks are cleaned up at 80 days too. Videos created before 2026-11-08 stay available until 2027-01-07 and are deleted after 2027-01-27. |
A video is available for 60 days after its task was created. After that the task still answers, with expired: true and no media links. 80 days after creation we delete the video, its versions, poster and preview, and the task keeps only its price and refund fields. Download a video you want to keep before expires_at. Videos created before 2026-11-08 stay available until 2027-01-07 and are deleted after 2027-01-27.
Uploaded files are deleted 3 days after the video that uses them is delivered, or 72 hours after upload if no delivered video uses them. Upload again to use a file in a later task. A request that names a deleted upload returns 410 media_expired (see Media links are private).
Storyboard modes
A video longer than 15s renders as a stitched multi-shot video. By default (mode: "auto"), the director plans and renders the whole video for you.
Two optional modes let you control the storyboard first. Both are video-only and need a duration over 15s:
- Advanced mode: you send your own storyboard.
- Edit mode: the director drafts a storyboard, and you edit it before the render.
Auto chaining works with every mode.
Advanced mode
Bring your own storyboard: pass a segments array instead of the director's plan. With mode: "auto" (or no mode), the video renders immediately.
curl -s -X POST "$NURETA_URL/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-d '{
"model": "seahorse-480p",
"content": [{ "type": "text", "text": "a moonlit rooftop encounter" }],
"ratio": "9:16",
"segments": [
{ "script": "she steps onto the rooftop, city lights behind her", "duration_seconds": 8 },
{ "script": "he joins her at the railing; they kiss", "duration_seconds": 10, "explicit": false },
{ "script": "the payoff shot", "duration_seconds": 12, "explicit": true }
]
}'Each item in segments is one stitched shot:
| Field | Required | Notes |
|---|---|---|
script | yes | The text of the shot. |
duration_seconds | no | 4–15. Default 9. |
first_frame, last_frame | no | Frame URLs that pin the opening or closing frame of the shot. Every shot can have them. A shot with explicit: true cannot have them, because a framed shot loses its anatomy references: such a task fails and is refunded. |
explicit | no | Whether the shot shows a sex act. See The explicit flag. |
chain_from_previous | no | true chains this shot to the shot before it. The first shot cannot set it. A video with chained shots renders one shot at a time. With auto_chain: true, every shot after the first chains, except a shot that sets this field itself or pins its own first_frame; false stops the chain at this shot. |
The shots must total 16–180s. That total becomes the duration and the price of the video.
Auto chaining
Set auto_chain: true on a video over 15s for smoother, more consistent joins between its shots. It works in auto, advanced and edit mode, at no extra charge: the same seconds render at the same price.
- Each shot in the same place opens on the last frame of the shot before it.
- A shot with
explicit: truedoes not get that frame as a first frame, because a first frame would drop its anatomy references. It gets the frame as one extra reference image instead. - A change of place is a cut. The shot after it does not chain.
- A shot chains only to a shot that passed the quality check.
- A shot that pins its own
first_frame, or setschain_from_previous: false, does not chain. In advanced mode, every shot after the first chains except such a shot. - If the renderer refuses a chained frame, that shot renders again without it. The video does not fail because of chaining.
The render takes longer. The shots render one after the other, not at the same time. The total time is close to the sum of the shot renders, not the time of the slowest shot, so a 180s video can take several times longer. A chained task also gets more time before the automatic timeout refund: 30 minutes more for each shot after the first (one shot per 9 seconds while the shots are not known yet).
On a delivered video, scene.segments[].chained is true on each shot that opened on the shot before it.
In edit mode, send auto_chain when you create the draft, or change it with the structured edit. The draft shows scene.autoChain after a structured edit set it.
The explicit flag
Read this. Per shot, explicit answers one question: does a real sex act happen in this shot?
The model (Seedance) has no built-in knowledge of sex acts or anatomy. So shots that should show sex go through a separate anatomy-reference pipeline, which attaches real anatomy references. Without these references, the model can only render soft or suggestive motion.
explicit: true: this shot depicts sex. You must describe the act concretely in thescriptorbeat: what each person does, for example position and contact. A vague line such as "they get closer" on an explicit shot produces no references and renders soft.explicit: false: a build-up or story shot (a look, a touch, undressing, afterglow). It renders from text only, with no anatomy references. This is correct, because you do not want sex to bleed into a build-up shot.
Set explicit: true only on the shots that should show sex, and make their text spell out the act. In edit mode, the AI director sets the flag for you. Override it per shot with /plan/structured. A beat whose words describe a sex act stays explicit: true, even if you send false.
Edit mode
Review and change the storyboard before the full render. Submit with mode: "edit", with or without your own segments.
curl -s -X POST "$NURETA_URL/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-d '{ "model": "seahorse-480p", "duration": 60, "mode": "edit",
"content": [{ "type": "text", "text": "a slow bedroom scene" }] }'The task is charged for the requested duration at submit. Edit mode never reprices: every edit and the render must keep the shot durations summing to scene.lockedDurationSeconds (the paid duration). An edit with another total returns 400 (InvalidParameter).
The task drafts a storyboard, then parks at status: "planned". Poll the task until status is planned.
The director's draft can total a different number of seconds than scene.lockedDurationSeconds, often fewer. scene.renderedDurationSeconds shows the current total. Edit the durations to sum to the locked total before you render.
The draft is in the scene field:
| Field | Meaning |
|---|---|
scene.segmentCount | The number of shots. |
scene.characterImage | A preview URL of the character: your own photo when one is used. |
scene.characterImageGenerated | true when that preview is a portrait drawn from your text (no usable photo of the person). |
scene.segments[].index | The 1-based shot index. |
scene.segments[].script | The shot's prompt. |
scene.segments[].durationSeconds | The shot's duration. |
scene.segments[].explicit | The explicit flag. |
scene.segments[].backgroundImage | A preview URL of the people-free background. |
scene.segments[].firstFrame, lastFrame | The pinned frames, if any. |
scene.autoChain | Auto chaining for the render, after a structured edit set it. Absent: as set at create. |
Edit a draft
Edit the parked draft with PUT …/tasks/:id/plan. Send only the shots you change, matched by their 1-based index. Each shot may set script, duration_seconds, first_frame, last_frame, or background_image. For the failures, see Edit errors.
curl -s -X PUT "$NURETA_URL/api/v3/contents/generations/tasks/cgt-.../plan" \
-H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-d '{ "segments": [
{ "index": 1, "script": "a tighter opening, close on her face", "duration_seconds": 8 },
{ "index": 2, "first_frame": "https://.../frame.jpg" }
] }'| Field | Notes |
|---|---|
index | Required. The 1-based shot index. |
script | The new prompt for the shot. |
duration_seconds | 4–15. |
first_frame, last_frame | A frame URL. null clears the frame. |
background_image | A hosted people-free image URL, or a library background library:bg_.... It replaces the background plate of the shot. null clears it. |
The response is the task view with the refreshed scene.
Frames vs. the character reference. A pinned first_frame or last_frame renders that shot frame-conditioned. For the render, the frame replaces the character and background reference of that shot, because the two cannot be combined. So the identity in the shot comes from the frame image itself. Pin a frame that already shows your character, or leave frames unset so the shared character reference keeps every shot consistent.
Structured edit
Edit the short action beat of each shot and let the server re-expand it into the full prompt. This is the recommended way to edit, because you do not write the full expanded prompt yourself.
PUT …/tasks/:id/plan/structured
curl -s -X PUT "$NURETA_URL/api/v3/contents/generations/tasks/cgt-.../plan/structured" \
-H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-d '{ "segments": [
{ "index": 1, "beat": "she wakes and stretches toward the window", "duration_seconds": 10 },
{ "beat": "a new insert: close on her hands", "duration_seconds": 5 },
{ "index": 2, "beat": "she crosses to the door", "duration_seconds": 5 }
] }'The segments array is the authoritative ordered set. The server matches shots by index:
- A shot whose
indexis missing from the array is removed. - An entry without
indexis inserted as a new shot. - The array order is the final order.
So reorder, add, and remove are free.
| Field | Required | Notes |
|---|---|---|
segments[].index | no | The 1-based index of an existing shot. Omit it, or give an index that no shot has, to insert a new shot. |
segments[].beat | yes | The action beat. |
segments[].explicit | no | The explicit flag. Omit it to keep the current flag. A beat that describes sex is always explicit. |
segments[].duration_seconds | no | 4–15. An existing shot keeps its duration. A new shot defaults to 9. |
segments[].first_frame, last_frame | no | A frame URL. |
segments[].background_image | no | Older storyboards only. A hosted people-free image URL, or a library background library:bg_..., that replaces the background plate of the shot. null drops it. A shot pinned with a frame ignores its background. |
world, wardrobe, character | no | Top level, older storyboards only (scene.continuityBible is null). They override the shared style. A change to any of them re-expands every non-explicit shot. |
auto_chain | no | Top level. true or false sets auto chaining for this draft's render. Omit it to keep the current setting. The edit re-expands the plan as usual. The shots in this body have no chain_from_previous: use auto_chain. |
For continuity storyboards, the body also takes bible and per-shot location and outfits. See Continuity storyboards.
GET shows the current shared world, wardrobe, and character on scene. It also shows the beat, the read-only setting, and the backgroundImage preview of each shot. So a resumed editor can seed every field.
Re-expansion
Re-expansion runs asynchronously. The call returns 202 with the task view, and status stays planned. Poll GET …/tasks/:id and read step.code and scene.reexpandStatus:
| State | step.code | scene.reexpandStatus |
|---|---|---|
| Running | reexpanding | "pending" |
| Ready | pending_rendering | "ready" |
| Failed | reexpand_failed | "failed", with the reason in scene.reexpandError |
When the state is ready, the refreshed scene.segments[].script holds the expanded prompts.
An edit sent while a re-expansion runs returns 409. Read status and step.code with GET.
Edit errors
Both edit routes (/plan and /plan/structured) return these errors:
| Status | Route | Meaning |
|---|---|---|
400 InvalidParameter | both | The shot durations do not sum to scene.lockedDurationSeconds. |
400 | both | The task was not created with mode: "edit". |
400 | /plan | An index matches no shot. |
409 | both | The task is not parked at planned. |
409 | both | A re-expansion runs. |
Continuity storyboards
New storyboards keep their shared setting in a continuity bible: the cast, the outfits of each person, and the locations. For these storyboards, scene.continuityBible is not null.
A continuity storyboard rejects a changed world, wardrobe, or character with 400. On /plan/structured, it also rejects any segment background_image key, even null, with 400. The error message says what to send instead.
Edit the setting with these top-level bible keys. bible.outfits and bible.locations use the ids in scene.continuityBible.
| Key | Shape | Rules |
|---|---|---|
bible.outfits | {"<id>": {"text": "…"}} | Rewrites an outfit. text is up to 500 characters: 1–12 items, each up to 120 characters. Separate items with commas, 、, ;, /, or new lines. A new outfit id also needs "owner": "<person's name>". null removes the outfit. |
bible.locations | {"<id>": {"text": "…", "photo": "…"}} | Rewrites a place, or adds one under a new id. A new place needs text. text is 1–500 characters. Send text, photo, or both. photo is a people-free image URL or a library background library:bg_... that becomes its background, or null. null for the whole entry removes the location. |
bible.people | {"<name>": {"face": "…", "build": "…"}} | Changes how a person looks. Only when scene.continuityBible.rules is 2. face is up to 200 characters and build up to 160. "" clears the field. You cannot clear face for a person whose image is made from it (for example, a person added without a photo). At most 8 people per edit. |
bible.cast | {"<name>": {"sex": "…", "description": "…", "photo": "…", "build": "…"}} | Adds a person under a new name: 1–40 characters, not already in the cast. On a task with a cast, an edit that takes the cast past your account's cast limit returns 400. A storyboard that already has more people keeps them, and an edit that adds no one still works. sex is required: "female" or "male". A photo (image URL, or a library character library:chr_...) or a description (up to 500 characters) is also required. On a rules-2 storyboard, the description becomes the person's face text and is cut to 200 characters. build is optional, up to 160 characters, only when scene.continuityBible.rules is 2. {"<name>": null} removes the person. |
bible.garments | {"<id>": {"text": "…", "owner": "…"}} | Rewrites or adds one garment. text is 1–500 characters. owner is required for a new garment id and must be a person in the cast. owner is ignored when you rewrite an existing id. null removes the garment. |
Location rules:
- A location that a shot still uses cannot be removed.
- At least one location must stay.
- A storyboard has at most as many locations as shots.
Each shot also takes two continuity keys:
| Key | Shape | Meaning |
|---|---|---|
segments[].location | a location id | Moves the shot to that location. |
segments[].outfits | {"<name>": "<outfit id>"} | Picks what each person wears at the start of the shot. A null value goes back to the planned outfit. |
To read the result, use the continuity fields of each shot:
scene.segments[].continuity.locationIdis the location of the shot.continuity.wearis what each person wears, as text.continuity.outfitslists only the outfits picked by hand. Empty means as planned.
As always, segments must list every shot, and the durations must still sum to the locked total.
# Set a background photo on a location. List EVERY shot (a missing one is removed),
# beats unchanged. The shots at that location are laid out again.
curl -s -X PUT "$NURETA_URL/api/v3/contents/generations/tasks/cgt-.../plan/structured" \
-H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-d '{ "bible": { "locations": { "<location id>": { "photo": "https://.../room.png" } } },
"segments": [
{ "index": 1, "beat": "<shot 1 beat, unchanged>" },
{ "index": 2, "beat": "<shot 2 beat, unchanged>" }
] }'Render a draft
Send the draft to render.
POST …/tasks/:id/render
curl -s -X POST "$NURETA_URL/api/v3/contents/generations/tasks/cgt-.../render" \
-H "Authorization: Bearer sk-..."The task then proceeds like any other task. Poll it to succeeded for content.video_url.
Make the shot durations sum to scene.lockedDurationSeconds before you render. A render of a draft with another total returns 422 InvalidParameter. The task stays planned and its charge does not change, so edit the durations and render again.
| Status | Meaning |
|---|---|
422 | The shot durations do not sum to scene.lockedDurationSeconds. Nothing is charged or refunded. |
409 | A re-expansion runs. |
409 | The task is not a parked draft (still drafting, rendering, done, failed, or cancelled), or it was already rendered. |
400 | The last re-expansion failed. Edit again first. |
400 | The task was not created with mode: "edit". |
404 | The task id is unknown, or it is an image or script task id. |
A draft that you do not render or edit for 24 hours is refunded automatically. The task then ends failed with error code DraftExpired.
Cancel a draft
Cancel a parked draft to get the full charge refunded immediately, without the wait for the 24h auto-refund.
POST …/tasks/:id/cancel
curl -s -X POST "$NURETA_URL/api/v3/contents/generations/tasks/cgt-.../cancel" \
-H "Authorization: Bearer sk-..."You can cancel only an edit-mode draft parked at status: "planned", also while a re-expansion runs. A draft that is still being written, or that has started rendering, cannot be cancelled. The task moves to the terminal status cancelled, which is distinct from failed.
| Status | Meaning |
|---|---|
409 | The edit-mode task is not parked at planned (still drafting, rendering, done, failed, or cancelled). A second cancel also returns 409. |
400 InvalidParameter | The task was created in auto mode. This applies in any state. |
404 | The task id is unknown, or it is an image or script task id. |
Fix part of a video
Re-render only the shots you do not like in a delivered multi-shot video. The video must be over 15s and status: "succeeded". You can re-render shots for 3 days after the video is delivered. After that, a quote or a re-render is refused with 409 window_expired. scene.rerenderUntil shows the end of the window.
The other shots are reused, and the API stitches the video again as a new version. The old version stays available.
A chained video can be re-rendered (see Auto chaining):
- A re-rendered chained shot chains again, to the shot before it as that shot is now.
- If the shot before it is re-rendered in the same request, the shot renders unchained: two neighbouring shots redone in one request join with a cut.
- A request that sets frames itself (
flow_from_previous,first_frame_at,last_frame_at,clear_frames) wins over the chain. - The join to the next shot can jump, because the next shot opened on the old ending. To smooth that join, fix the next shot after this re-render is done, in a new request.
A video that was chained before chained shots could be re-rendered stays not re-renderable: scene.rerenderable is false, and the quote's reason is chained_frames.
Fix one shot step by step
GET …/tasks/:id. Checkscene.rerenderable, and check thatscene.rerenderUntil(unix seconds) is still in the future. Notescene.planVersionand thescene.segments[].idof the shot.POST …/rerender/quotewith that shot and anintent. Checkeligibleandprice_usd. For afix, show your userfix_plans(what will change).POST …/rerenderwith the same body and anIdempotency-Keyheader.- Poll
GET …/rerenders/:rerender_iduntil the run is finished. - Optional: pick other takes with
POST …/restitch, or go back to an older version withPOST …/versions/:v/current. - After
stitch_failed: apply the rendered takes for free withPOST …/restitch. See Free apply afterstitch_failed.
What GET shows
GET …/tasks/:id shows what you need:
| Field | Meaning |
|---|---|
scene.planVersion | The plan version to send as plan_version. |
scene.rerenderable | Whether the video can be re-rendered. |
scene.rerenderUntil | The end of the re-render window, in unix seconds. |
scene.rerenderReasons | Why the video cannot be re-rendered, when it cannot. |
scene.segments[].id | Stable shot ids. |
scene.segments[].chained | true when the shot opened on the last frame of the shot before it. Re-rendering the shot before it can make this join jump. |
scene.currentVersion, scene.versions[] | The versions. Each version has picks ({shot id: rev}, the takes it uses). It also has a timeline of where every shot starts and ends in that version. |
scene.takes | Every rendered result per shot, by rev. |
scene.restitchTakes, scene.restitchUntil | The free apply after stitch_failed. See below. |
scene.rerenders | The runs as the storyboard sees them. |
content.version, content.versions[] | The video_url of each version. |
rerender | The open run, or null. This field, rerenders[], and usage.rerenders[] are absent until the task has its first run. |
rerenders[] | Every run, in the full run shape. |
usage.rerenders[] | id, seconds, price_usd, refunded_usd, status. |
scene.rerenderable, scene.rerenderUntil, scene.rerenderReasons, and scene.planVersion show the state at delivery, at the last finished run, or at the last version switch. So they do not show an expired window. A finished run and a version switch both change scene.planVersion. Read the task again before the next quote.
The eligible and reasons of a quote are the current answer.
Quote
Get the price of a re-render. A quote is free and is never charged.
POST …/tasks/:id/rerender/quote
curl -s -X POST "$NURETA_URL/api/v3/contents/generations/tasks/cgt-.../rerender/quote" \
-H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-d '{ "plan_version": 3,
"segments": [
{ "id": "s_3f9a", "intent": "fix", "locale": "en",
"issues": [
{ "at": 2.5, "kind": "clothes", "wrong": "he still wears his shorts",
"want": "he is fully naked" },
{ "at": 6.1, "kind": "action", "wrong": "she lies on her back",
"want": "she kneels and he takes her from behind" }
] },
{ "id": "s_81c2", "intent": "retry" }
] }'Send plan_version and name the shots by id. For each shot, say what to do with an intent. The default is retry.
intent | Extra fields | Meaning |
|---|---|---|
retry | none | Same shot, new attempt. |
different_take | none | A different take. |
fix | issues, optional beat, locale | Fix what's wrong. Say when, what is wrong and what it should be, and we plan the change. See Fix what's wrong. |
wrong_action | beat, optional explicit | Deprecated: use fix. The action is wrong. Send a new beat. |
camera | beat | Deprecated: use fix. The camera is wrong. Send a new beat. |
body_face | none | The body or the face is wrong. |
wrong_clothes | none | The clothes are wrong. Not available yet: seahorse refuses it today, and a quote or start returns 422 intent_unavailable. Use fix with clothes. |
flow_from_previous | none | The shot does not flow from the previous shot. |
advanced | beat, explicit, first_frame_at, last_frame_at, clear_frames | first_frame_at and last_frame_at are times in seconds in the current version. |
Frames only ever come from this video. Image URLs are not accepted.
The deprecated intents still work for now. New code should send fix.
Fix what's wrong
With intent: "fix", you list the problems your user saw in issues: for each one, when it happens, its type, what is wrong and what it should be. We plan the change and the quote shows it in fix_plans before anything is charged.
| Field | Meaning |
|---|---|
issues | 1 to 8 problems, each { at, kind, wrong, want } (below). They are kept in the order you send. |
beat | Optional. The shot's description as your user edited it (start from scene.segments[].beat). At most 2000 characters. Send it only when your user changed it. The re-render then follows it, with each want at its time. |
locale | The language of your UI, as a tag such as en or zh-CN (at most 16 characters). The plan's summary is written in it. |
Each item of issues:
| Field | Meaning |
|---|---|
at | When it happens, in seconds from the start of this shot (not of the video), >= 0. A time at most 1 s past the end of the shot counts as its end; later is 422 at_out_of_range. |
kind | The type, from the table below. |
wrong | What is wrong, in your user's words. 1 to 300 characters, without the spaces around it. |
want | What it should be, as a full sentence (for example "He is on the right side of the bed"). 1 to 300 characters, not the same as wrong. |
kind | Meaning |
|---|---|
body | A body looks wrong (face, limbs, genitals, size). |
action | Wrong act or position. |
clothes | The clothes are wrong. |
camera | The camera or the view is wrong. |
pace | Too fast or too slow. |
speech | Talking or sound is wrong. |
not_visible | You cannot see the action. |
other | Something else. |
Rules, checked before any call. A broken rule returns 400 with the rule as error.code, the shot as error.segment_id, and for issue_incomplete the position as error.index. Seahorse uses the same codes (as 422), so match the code, not the status:
issues_required: afixwithissuesneeds at least one problem.issue_incomplete:<index>: the problem at that position (from 0, as sent) has no validkind, a blank or too longwrongorwant, awantequal towrong(case and surrounding spaces are ignored), or a badat. Match the code by its prefixissue_incomplete:.too_many_issues: at most 8 problems per shot.mixed_fields:issuescannot go together with a non-emptyproblems, a non-blanknote, anator abody_issue, and only withintent: "fix".too_many_fixes(400 InvalidParameter, the message names it): at most 4 shots withfixin one request. You can retry more shots in the same request.
Old fix fields (deprecated)
Before issues, a fix said what was wrong with problems, body_issue, note and at. These fields still work as before until at least 2026-12-15. Do not send them in new code, and never together with issues.
| Field | Meaning |
|---|---|
problems | 1 to 8 different values of kind (above). Required when you send no beat. |
body_issue | Required with body. One of face_changed, extra_or_missing_limb, genitals_wrong, body_look. |
note | What it should be. At most 500 characters. Required with other when you send no beat. |
at | Where the problem is, in seconds from the start of this shot. |
Their rules: problems_required (a fix without issues needs problems or a changed beat), body_issue_required (body needs body_issue), note_required (other needs a note, unless you send a beat).
Quote a fix before you start it. The start uses only the plan that the quote showed. If that plan is no longer kept (about 6 hours), the start returns 409 quote_expired and nothing is charged: quote again, show the new plan, then start. The other intents work as before.
note, at and body_issue are also accepted on the other intents (not fix with issues), as quality feedback only. All these fields are part of the quote: send the same values to the quote and to the start.
The quote returns:
| Field | Meaning |
|---|---|
eligible | Whether the re-render can start. |
reasons | Why not, when eligible is false. |
segments[] | id, intent, seconds, price_usd per shot. |
seconds | The total seconds to re-render. |
price_usd | The total price. |
quote_hash | The hash of the quote. |
policy | The content check of your edited text, as { ok, verdict }. |
fix_plans | Per fix shot id: { summary, refused, kept, own, issues }. {} when the request has no fix. |
Each plan in fix_plans:
summary: what the re-render will change, inlocale. Show it to your user as "We will: …".kept:truewhen the plan already shows what your user wants. The re-render is then a new take focused on the problems, with the same plan.own:truewhen the re-render uses your user's ownbeatas written. Show it as "We will use your description: …";summaryis that text.refused:null, or why the fix is not possible:new_person,new_place,locked_param,camera_rule,unclear,unclear_issue(we could not tell what one problem should be),one_main_change(the problems ask for more than one main change in this shot) orother. The quote is then not eligible, with the reasonfix_not_possible:<code>.issues: only for a fix sent withissues. One{ index, refused }per problem, whereindexis its position as you sent it andrefusedisnullor the code that names that problem (for exampleunclear_issue). Show the refusal on that problem, such as "Problem at 0:03: say what it should be".
A quote that is not eligible has empty segments, zero seconds and price_usd, and null for quote_hash and policy. It still has fix_plans.
Start a re-render
Start a paid re-render run.
POST …/tasks/:id/rerender
curl -s -X POST "$NURETA_URL/api/v3/contents/generations/tasks/cgt-.../rerender" \
-H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2e0a-fix-1" \
-d '{ "plan_version": 3, "segments": [{ "id": "s_81c2", "intent": "retry" }] }'Send the same body as the quote. Add an Idempotency-Key header so that a retried request is charged once:
- The same key with a different body returns
422. - A key is kept for 24 hours.
- If the start is refused, the net charge is zero and the key is freed. You can send the same request again.
- A refusal can come after the charge (for example
plan_changed,quote_changed,rerender_busy, orprompt_policy_rejected). Then the API keeps afailedrun with a full refund (refunded_usdequalsprice_usd). Itserror.codeis the refusal code, and it has no per-shotstatus. A webhook is sent for that run.
The response is 201 { rerender_id, seconds, price_usd, status }.
A retry with a used key returns 201 with the same run and its current status. That status can be failed or aborted when the run never started or was stopped. The API refunded that run, so send a new key to try again.
Poll a run
Get the state of one run.
GET …/tasks/:id/rerenders/:rerender_id
To list all runs, use GET …/tasks/:id/rerenders. It returns { items }.
status is queued, then running, then one of succeeded, partial, stitch_failed, failed, or aborted.
| Field | Meaning |
|---|---|
id | The run id. |
kind | rerender or restitch. |
status | The run status. |
segments[] | id, intent, seconds, rev, status per shot. |
seconds | The seconds re-rendered. |
price_usd | The price. |
refunded_usd | The refunded amount. |
version | The new version. |
video_url | The video of the new version. |
error | { code, message } or null. |
created_at, updated_at | When the run was created and last updated. |
The per-shot status works like this:
- While a run is open, the
statusof each shot is live. Use it to show how many shots are done. - A run that started and ends as
succeeded,partial,stitch_failed, orfailedkeeps the finalstatusof each shot. - A stopped run (
aborted) has no per-shotstatus. Neither does a run that never started (failedwitherror.codenot_started, or with a refusal code after the charge).
On succeeded or partial, the content.video_url of the task is the new version. The status of the task stays succeeded the whole time. The API serves the old video until the new one is ready.
When the task has a callback_url, each finished run sends a generation.task.rerender.completed webhook. The event name is in the body and in the x-nureta-event header. The body has the rerender and the full task.
Re-stitch and switch versions
Both calls are free.
Pick any rendered takes and stitch them as a new version with POST …/tasks/:id/restitch and { "picks": { "s_81c2": 1 } }. picks is {shot id: rev} and may name only some shots. The call returns 202 with the run (kind: "restitch").
Switch back to any version with POST …/tasks/:id/versions/:v/current. The call returns the task view.
Free apply after stitch_failed
After a stitch_failed run, scene.restitchTakes can be set. This can happen inside the re-render window or after it.
When it is set, send POST …/tasks/:id/restitch with { "picks": <scene.restitchTakes> } before scene.restitchUntil. That is at most 7 days after the run ended. The call stitches the takes you paid for, free of charge. After scene.rerenderUntil, this is the only re-stitch the API accepts.
Pricing and refunds
A re-render costs the seconds of the re-rendered shots × the per-second price of the task's model. This is the same rate as the original, with no extra fee. Re-stitching and switching versions are free.
- Text that the content check blocks is never charged. If the check blocks it after the charge, you get a full refund.
- Shots that fail are refunded per shot. The shots that worked are delivered (
partial). Afixshot whose planned change could not be applied fails withfix_not_appliedand is refunded. - A run that fails, or that is stopped after about 2 hours, is refunded in full.
- A run stopped by a delete refunds only the shots that were not yet sent to render.
stitch_failed(joining the shots failed): the shots that failed are refunded. You keep the shots that rendered, and they are not refunded. Re-stitch them for free.- Not liking the result is not refunded. Switch back to an older version for free.
Errors
Each error body has a stable code. A refused quote or start costs nothing in the end. A start refused after the charge is refunded in full.
| Status | code | Meaning |
|---|---|---|
400 | InvalidParameter | The body is not valid (plan_version, segments, picks). Or the Idempotency-Key is not 1–255 visible ASCII characters. Or the video is not a multi-shot video. |
403 | AccountOverdueError | Your balance is lower than the price. |
404 | NotFound | Re-render is not available on this service. Or the task, version, or run is unknown. |
409 | Conflict | The task has not succeeded. |
422 | IdempotencyKeyReused | This Idempotency-Key was used with a different body or another task. |
422 | plan_changed | The video changed since you read it. Read the task again and send the new plan_version. |
422 | unknown_segment, beat_required, intent_unavailable, no_previous_clip, no_frames, at_out_of_range | The request does not fit this video: an unknown shot id, a missing beat, an unavailable intent, flow_from_previous on the first shot, clear_frames on a shot without frames, or an at past the end of the shot. |
422 | issues_required, issue_incomplete:<index>, too_many_issues, mixed_fields, too_many_fixes, and the deprecated problems_required, body_issue_required, note_required | A fix breaks a rule (see Fix what's wrong). The API checks these first: the issues codes come back as 400 with that code, the others as 400 InvalidParameter. Match issue_incomplete: by its prefix. |
409 | fix_not_possible:<code> | A quote reason: the fix is not possible. fix_plans says why, and fix_plans[id].issues names the problem. Change that problem. |
409 | quote_expired | The plan of a fix was not quoted, or is no longer kept. Quote again, then start. |
422 | prompt_policy_rejected | The content check blocked the edited text. |
422 | policy_unchecked | The content check gave no answer. Try again. |
409 | window_expired, chained_frames, single_segment, clips_not_saved, deleted, not_a_delivered_scene | The video cannot be re-rendered. These are the quote's reasons. not_eligible when the quote gives no reason. chained_frames: a video chained before chained shots could be re-rendered. |
409 | rerender_running, scene_busy | A run of this video is still open. Wait for it to finish. |
409 | quote_changed, start_expired | The video or the price changed after the quote, or the run did not start in time. Quote again. |
409 | restitch_unchanged, restitch_limit | Re-stitch only. These takes already make a version, or the video already has 30 versions. |
422 | unknown_take | Re-stitch only. A shot in picks has no take with that rev. |
429 | too_many_rerenders | Two runs are already open on your account. |
429 | quote_running | A quote (or the quote that a start runs) for this video is already in progress, or two are in progress on your account. Wait for one to finish. |
429 | RateLimitExceeded | More than 12 quote, re-render, or re-stitch requests in one minute. |
503 | rerender_busy, queue_unavailable, fix_planner_busy | The service is busy, or the fix could not be planned now. Nothing was charged. Try again in a few minutes. |
503 | start_in_progress | A start with this Idempotency-Key is still being processed. Its outcome is not known yet: retry with the same key. |
Limits
- One run (re-render or re-stitch) at a time per video. A second one returns
409 rerender_running. A version switch during a run returns409 scene_busy. You can fix several shots in one run. - Re-render and re-stitch runs together run at most two at a time per account. A run beyond that returns
429 too_many_rerenders. - Quote, re-render, and re-stitch together accept 12 requests per minute per account.
- One quote at a time per video, and two at a time per account. A start also runs a quote. One more while those are in progress returns
429 quote_running. - A run that is not finished after 75 minutes is ended early. The shots that are done become a new version (
partial), and the other shots are refunded. If no shot is done, the run fails and is refunded in full. - A run that is still open after about 2 hours is stopped and refunded in full.
- Deleting a video stops its running re-render first. The shots that were not sent to render yet are refunded. If the run cannot be stopped, the delete returns
409and the video is not deleted. Try again shortly.
Models & pricing
GET /api/v3/models (public) returns the current models and their USD prices. Each model has:
- A per-second price and a per-5s price.
prices: the price of each value in itsdurationslist. The list is 5, 8, 10, 12, and 15, plus the presets 30, 60, 90, 120, and 180 onseahorse-<res>models. Other durations cost the per-second price × seconds.
For direct Seedance models, these prices are for 720p. price_usd_per_5s_by_resolution gives the per-5s price of each resolution.
Three resolutions are offered. A seahorse-1080p video takes a few extra minutes. The price scales linearly with duration: a single clip of 5, 8, 10, 12, or 15s, or a stitched multi-shot video of any integer from 16 to 180s. Legacy seahorse-fast-<res> ids still work as aliases.
Looking for the app?
This is API pricing. Looking for the app? Consumer pricing is $1.29 per 5-second 480p video ($2.58 at 720p, $3.87 at 1080p). The first video is free: a 5-second 480p clip with Google sign-in (small watermark). The Nureta app and the Nureta Developer API both offer 480p, 720p and 1080p. See nureta.ai/en/pricing.
Seahorse models (Nureta's own pipeline with NSFW enhancement, 5-180 s multi-scene) start at $0.1888/s. The direct Seedance 2.0 models start at $0.0885/s (single clips, no NSFW enhancement).
| Model | Resolution | USD / sec | USD / 5s |
|---|---|---|---|
seahorse-480p | 480p | $0.1888 | $0.9440 |
seahorse-720p | 720p | $0.2773 | $1.3864 |
seahorse-1080p | 1080p | $0.5428 | $2.7139 |
Direct Seedance models
seedance2.0-fast and seedance2.0-pro call the Seedance 2.0 API directly. Your prompt and reference media go to Seedance verbatim: no prompt enhancement, no scene direction, no reference retrieval.
Use them when you want full control over exactly what Seedance receives. They are also the only way to use Seedance 2.0 Pro.
Differences from the seahorse-<res> models:
resolutionis a request parameter (480por720p, default720p). The price follows it. For 1080p, useseahorse-1080p.- Single clips only:
durationmust be 5, 8, 10, 12, or 15 seconds. No multi-shot videos, nomodeorsegments. - No enhancement fee. You pay the raw generation cost plus the standard margin.
| Model | Resolution | USD / sec | USD / 5s |
|---|---|---|---|
seedance2.0-fast | 480p | $0.0885 | $0.4425 |
seedance2.0-fast | 720p | $0.1770 | $0.8850 |
seedance2.0-pro | 480p | $0.1770 | $0.8850 |
seedance2.0-pro | 720p | $0.3540 | $1.7699 |
curl -s -X POST "$NURETA_URL/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer sk-..." \
-H "Content-Type: application/json" \
-d '{
"model": "seedance2.0-pro",
"resolution": "720p",
"content": [
{"type": "text", "text": "your exact Seedance prompt, sent as-is"},
{"type": "image_url", "image_url": {"url": "https://example.com/ref.jpg"}}
],
"duration": 5
}'