● nureta
Docs

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_url item 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 own first_frame and last_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

FieldRequiredNotes
modelyesseahorse-480p, seahorse-720p, or seahorse-1080p. Or a direct Seedance model: seedance2.0-fast or seedance2.0-pro. See Models & pricing.
resolutionnoDirect 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.
contentyes (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[].typeyestext, image_url, library_item, or audio_url.
image_url.urlfor image_urlAn 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.idfor library_itemThe id of one of your saved library items: chr_... (a character) or bg_... (a background). See Library items in a video.
personwith castOn a face image_url or a character library_item: the cast id (p1–p8) of the person in the photo. See Cast.
castnoThe people of the video, with ids. See Cast. Not with last_frame. With first_frame only together with photo_split_id.
photo_splitno"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_idnoThe 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.
rolenoSet 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.urlfor audio_urlAn 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.
rationoDefault 16:9. Allowed: 16:9, 9:16, 4:3, 3:4, 1:1, 21:9, adaptive.
durationnoDefault 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_audionoDefault true.
musicnoBackground 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_notenoYour 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.
modenoDefault auto (fully automated). Set edit to get a storyboard draft that you can edit before the render. See Storyboard modes. Video only, >15s.
segmentsnoAdvanced 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_chainnoDefault 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_urlnoAn HTTPS endpoint. The API POSTs the terminal task response to it. See Callback webhook.
callback_secretnoAn 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 sendSingle clip (≤15 s)Multi-shot videoStoryboard 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_found before 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's scene already holds.
  • The task view lists an item in media as library:chr_... or library: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.

FieldRequiredNotes
cast.membersyes, with castAt 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[].idyesp1 to p8, each id once. content[].person and cast.camera use it.
members[].sexyesfemale or male.
members[].nameno1–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[].looksnoUp to 120 characters, for example "freckles, short red hair".
members[].outfitnoUp to 120 characters.
cast.cameranoThe 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[].personwith cast, on every person photoOn 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"noOn 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 (an image_url with no role, or a character library_item) has a person, and a person has at most one photo.
  • A person photo is your own: the assetUrl of an upload from your account, or a saved library character. Any other link is refused (another account's upload: 403 MediaNotOwned).
  • The cast.camera person has no photo (no person that 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 a bg_... item), a pose, or a frame has no person.
  • cast cannot be used with last_frame, also not on a segments[] item or in a storyboard edit (a frame drops every reference image).
  • cast with first_frame needs the photo_split_id of the split whose opening frame it is. A segments[] item takes no frame with a cast.
  • A character library_item has the same sex as its person.
  • person or role: "pose" without cast.
  • cast on 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.codeMeaning
400 cast_disabledCasts are not available for your account. Send the request without cast.
400 cast_too_largeThe 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_allowedThis 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_unavailableThe 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:

FieldMeaning
photo_splitThe 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.
castThe people the split made, when the request had no cast.
input_warningsphoto_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_large with error.reason: "in_clip" and error.max_in_clip. Nothing is charged.
  • A longer video: the task fails with error.code cast_too_large when 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:

FieldMeaning
castYour 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_peopleThe people in each shot, as {"0": ["p1", "p2"], "1": ["p1"]} (shot index from 0, then cast ids).
input_warningsCodes 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.personOn 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.codeMeaning
cast_disabledCasts are not available for your account. Send the request without cast.
cast_invalidA cast field or a person is not valid.
cast_too_largeThe 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_allowedThis mix of women and men is not available. Change the cast.
cast_text_rejectedThe content policy blocked a name, looks or outfit.
input_media_no_faceThe 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_facesA 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.

FieldType or valuesMeaning
idstringThe task id.
modelstringThe model.
statusqueued, running, planned, succeeded, failed, or cancelledThe task status.
resolutionstringThe resolution.
ratiostringThe aspect ratio.
durationnumberThe video duration in seconds.
created_at, updated_atinteger (Unix seconds)When the task was created and last updated.
stepobjectProgress. See Progress (step).
usageobjectprice_usd and refunded. Also rerenders[] once a re-render ran.
promptstringYour prompt.
mediaarrayYour 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_warningsobject, object, arrayOnly on a task with a cast. See Cast.
first_frame, last_framestringYour pinned frames. Only when set.
modeauto or editOn every video task.
sceneobjectThe storyboard. Only on a storyboard task.
contentobjectThe result. Only when succeeded, and not after the video expired.
errorobjectThe failure. Only when failed.
expires_atinteger (Unix seconds)When the video expires: 60 days after created_at. After that no response carries its links.
expiredbooleantrue after expires_at. The task has no content, and every media link in it is null. Re-render calls return 410 video_expired.
rerenderobject or nullGET only, when the video has re-render runs. The open run, or null.
rerenders[]arrayGET 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:

codeModeMeaning
queuedallQueued.
generating_scriptallGenerating the script.
generating_visualsallGenerating the visuals.
pending_renderingedit onlyThe draft is parked and waits for your render.
renderingallRendering. done and total appear only in this phase: clips completed and total clips.
stitchingallStitching the shots.
reexpandingedit onlyA structured re-expansion runs.
reexpand_failededit onlyThe last re-expansion failed. Edit again before you render.
done, failed, cancelledallTerminal 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-..."
ParameterValuesMeaning
limit1–100, default 20Page size. A value out of range is clamped.
offsetintegerThe 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.

StatusMeaning
409 ConflictThe task is not finished. For a parked draft (planned), cancel it first. You can delete a running task when it finishes.
409The running re-render could not be stopped. Try again shortly.
404 NotFoundThe task id is unknown, or it is an image or script task id.
429 RateLimitExceededYour account already deleted 10 tasks in the last minute. All task kinds count.

Data retention

DataDeleted
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 previewViewable 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:

FieldRequiredNotes
scriptyesThe text of the shot.
duration_secondsno4–15. Default 9.
first_frame, last_framenoFrame 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.
explicitnoWhether the shot shows a sex act. See The explicit flag.
chain_from_previousnotrue 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: true does 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 sets chain_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 the script or beat: 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:

FieldMeaning
scene.segmentCountThe number of shots.
scene.characterImageA preview URL of the character: your own photo when one is used.
scene.characterImageGeneratedtrue when that preview is a portrait drawn from your text (no usable photo of the person).
scene.segments[].indexThe 1-based shot index.
scene.segments[].scriptThe shot's prompt.
scene.segments[].durationSecondsThe shot's duration.
scene.segments[].explicitThe explicit flag.
scene.segments[].backgroundImageA preview URL of the people-free background.
scene.segments[].firstFrame, lastFrameThe pinned frames, if any.
scene.autoChainAuto 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" }
      ] }'
FieldNotes
indexRequired. The 1-based shot index.
scriptThe new prompt for the shot.
duration_seconds4–15.
first_frame, last_frameA frame URL. null clears the frame.
background_imageA 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 index is missing from the array is removed.
  • An entry without index is inserted as a new shot.
  • The array order is the final order.

So reorder, add, and remove are free.

FieldRequiredNotes
segments[].indexnoThe 1-based index of an existing shot. Omit it, or give an index that no shot has, to insert a new shot.
segments[].beatyesThe action beat.
segments[].explicitnoThe explicit flag. Omit it to keep the current flag. A beat that describes sex is always explicit.
segments[].duration_secondsno4–15. An existing shot keeps its duration. A new shot defaults to 9.
segments[].first_frame, last_framenoA frame URL.
segments[].background_imagenoOlder 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, characternoTop 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_chainnoTop 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:

Statestep.codescene.reexpandStatus
Runningreexpanding"pending"
Readypending_rendering"ready"
Failedreexpand_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:

StatusRouteMeaning
400 InvalidParameterbothThe shot durations do not sum to scene.lockedDurationSeconds.
400bothThe task was not created with mode: "edit".
400/planAn index matches no shot.
409bothThe task is not parked at planned.
409bothA 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.

KeyShapeRules
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:

KeyShapeMeaning
segments[].locationa location idMoves 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.locationId is the location of the shot.
  • continuity.wear is what each person wears, as text.
  • continuity.outfits lists 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.

StatusMeaning
422The shot durations do not sum to scene.lockedDurationSeconds. Nothing is charged or refunded.
409A re-expansion runs.
409The task is not a parked draft (still drafting, rendering, done, failed, or cancelled), or it was already rendered.
400The last re-expansion failed. Edit again first.
400The task was not created with mode: "edit".
404The 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.

StatusMeaning
409The edit-mode task is not parked at planned (still drafting, rendering, done, failed, or cancelled). A second cancel also returns 409.
400 InvalidParameterThe task was created in auto mode. This applies in any state.
404The 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

  1. GET …/tasks/:id. Check scene.rerenderable, and check that scene.rerenderUntil (unix seconds) is still in the future. Note scene.planVersion and the scene.segments[].id of the shot.
  2. POST …/rerender/quote with that shot and an intent. Check eligible and price_usd. For a fix, show your user fix_plans (what will change).
  3. POST …/rerender with the same body and an Idempotency-Key header.
  4. Poll GET …/rerenders/:rerender_id until the run is finished.
  5. Optional: pick other takes with POST …/restitch, or go back to an older version with POST …/versions/:v/current.
  6. After stitch_failed: apply the rendered takes for free with POST …/restitch. See Free apply after stitch_failed.

What GET shows

GET …/tasks/:id shows what you need:

FieldMeaning
scene.planVersionThe plan version to send as plan_version.
scene.rerenderableWhether the video can be re-rendered.
scene.rerenderUntilThe end of the re-render window, in unix seconds.
scene.rerenderReasonsWhy the video cannot be re-rendered, when it cannot.
scene.segments[].idStable shot ids.
scene.segments[].chainedtrue 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.takesEvery rendered result per shot, by rev.
scene.restitchTakes, scene.restitchUntilThe free apply after stitch_failed. See below.
scene.rerendersThe runs as the storyboard sees them.
content.version, content.versions[]The video_url of each version.
rerenderThe 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.

intentExtra fieldsMeaning
retrynoneSame shot, new attempt.
different_takenoneA different take.
fixissues, optional beat, localeFix what's wrong. Say when, what is wrong and what it should be, and we plan the change. See Fix what's wrong.
wrong_actionbeat, optional explicitDeprecated: use fix. The action is wrong. Send a new beat.
camerabeatDeprecated: use fix. The camera is wrong. Send a new beat.
body_facenoneThe body or the face is wrong.
wrong_clothesnoneThe 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_previousnoneThe shot does not flow from the previous shot.
advancedbeat, explicit, first_frame_at, last_frame_at, clear_framesfirst_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.

FieldMeaning
issues1 to 8 problems, each { at, kind, wrong, want } (below). They are kept in the order you send.
beatOptional. 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.
localeThe 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:

FieldMeaning
atWhen 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.
kindThe type, from the table below.
wrongWhat is wrong, in your user's words. 1 to 300 characters, without the spaces around it.
wantWhat 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.
kindMeaning
bodyA body looks wrong (face, limbs, genitals, size).
actionWrong act or position.
clothesThe clothes are wrong.
cameraThe camera or the view is wrong.
paceToo fast or too slow.
speechTalking or sound is wrong.
not_visibleYou cannot see the action.
otherSomething 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: a fix with issues needs at least one problem.
  • issue_incomplete:<index>: the problem at that position (from 0, as sent) has no valid kind, a blank or too long wrong or want, a want equal to wrong (case and surrounding spaces are ignored), or a bad at. Match the code by its prefix issue_incomplete:.
  • too_many_issues: at most 8 problems per shot.
  • mixed_fields: issues cannot go together with a non-empty problems, a non-blank note, an at or a body_issue, and only with intent: "fix".
  • too_many_fixes (400 InvalidParameter, the message names it): at most 4 shots with fix in 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.

FieldMeaning
problems1 to 8 different values of kind (above). Required when you send no beat.
body_issueRequired with body. One of face_changed, extra_or_missing_limb, genitals_wrong, body_look.
noteWhat it should be. At most 500 characters. Required with other when you send no beat.
atWhere 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:

FieldMeaning
eligibleWhether the re-render can start.
reasonsWhy not, when eligible is false.
segments[]id, intent, seconds, price_usd per shot.
secondsThe total seconds to re-render.
price_usdThe total price.
quote_hashThe hash of the quote.
policyThe content check of your edited text, as { ok, verdict }.
fix_plansPer 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, in locale. Show it to your user as "We will: …".
  • kept: true when 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: true when the re-render uses your user's own beat as written. Show it as "We will use your description: …"; summary is 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) or other. The quote is then not eligible, with the reason fix_not_possible:<code>.
  • issues: only for a fix sent with issues. One { index, refused } per problem, where index is its position as you sent it and refused is null or the code that names that problem (for example unclear_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, or prompt_policy_rejected). Then the API keeps a failed run with a full refund (refunded_usd equals price_usd). Its error.code is the refusal code, and it has no per-shot status. 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.

FieldMeaning
idThe run id.
kindrerender or restitch.
statusThe run status.
segments[]id, intent, seconds, rev, status per shot.
secondsThe seconds re-rendered.
price_usdThe price.
refunded_usdThe refunded amount.
versionThe new version.
video_urlThe video of the new version.
error{ code, message } or null.
created_at, updated_atWhen the run was created and last updated.

The per-shot status works like this:

  • While a run is open, the status of each shot is live. Use it to show how many shots are done.
  • A run that started and ends as succeeded, partial, stitch_failed, or failed keeps the final status of each shot.
  • A stopped run (aborted) has no per-shot status. Neither does a run that never started (failed with error.code not_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). A fix shot whose planned change could not be applied fails with fix_not_applied and 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.

StatuscodeMeaning
400InvalidParameterThe 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.
403AccountOverdueErrorYour balance is lower than the price.
404NotFoundRe-render is not available on this service. Or the task, version, or run is unknown.
409ConflictThe task has not succeeded.
422IdempotencyKeyReusedThis Idempotency-Key was used with a different body or another task.
422plan_changedThe video changed since you read it. Read the task again and send the new plan_version.
422unknown_segment, beat_required, intent_unavailable, no_previous_clip, no_frames, at_out_of_rangeThe 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.
422issues_required, issue_incomplete:<index>, too_many_issues, mixed_fields, too_many_fixes, and the deprecated problems_required, body_issue_required, note_requiredA 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.
409fix_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.
409quote_expiredThe plan of a fix was not quoted, or is no longer kept. Quote again, then start.
422prompt_policy_rejectedThe content check blocked the edited text.
422policy_uncheckedThe content check gave no answer. Try again.
409window_expired, chained_frames, single_segment, clips_not_saved, deleted, not_a_delivered_sceneThe 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.
409rerender_running, scene_busyA run of this video is still open. Wait for it to finish.
409quote_changed, start_expiredThe video or the price changed after the quote, or the run did not start in time. Quote again.
409restitch_unchanged, restitch_limitRe-stitch only. These takes already make a version, or the video already has 30 versions.
422unknown_takeRe-stitch only. A shot in picks has no take with that rev.
429too_many_rerendersTwo runs are already open on your account.
429quote_runningA 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.
429RateLimitExceededMore than 12 quote, re-render, or re-stitch requests in one minute.
503rerender_busy, queue_unavailable, fix_planner_busyThe service is busy, or the fix could not be planned now. Nothing was charged. Try again in a few minutes.
503start_in_progressA 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 returns 409 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 409 and 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 its durations list. The list is 5, 8, 10, 12, and 15, plus the presets 30, 60, 90, 120, and 180 on seahorse-<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).

ModelResolutionUSD / secUSD / 5s
seahorse-480p480p$0.1888$0.9440
seahorse-720p720p$0.2773$1.3864
seahorse-1080p1080p$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:

  • resolution is a request parameter (480p or 720p, default 720p). The price follows it. For 1080p, use seahorse-1080p.
  • Single clips only: duration must be 5, 8, 10, 12, or 15 seconds. No multi-shot videos, no mode or segments.
  • No enhancement fee. You pay the raw generation cost plus the standard margin.
ModelResolutionUSD / secUSD / 5s
seedance2.0-fast480p$0.0885$0.4425
seedance2.0-fast720p$0.1770$0.8850
seedance2.0-pro480p$0.1770$0.8850
seedance2.0-pro720p$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
  }'

Guides