Reference images and videos
Some video models take references: a picture, a clip, a sound or a frame that the generated video should keep
consistent, such as a character, an object or a voice. You send them as parts of the content array (see
Roles).
Seedance takes references on two routes that prepare every picture, clip, sound and frame you send before the generation is submitted, so the generator accepts each of them in its role:
POST /v1/generations/refs, in our format: submit, then pollGET /v1/generations/{job_id}. Most of this page describes it./v1/modelark, in the vendor's own format (see the vendor-format route).
Use them when the ordinary Seedance route refuses a reference before anything is generated (see Errors).
People in references
Treat the people in your references as characters — generated or virtual people, or people you are entitled to show. If any image, clip or sound you send shows or voices a real, identifiable person, you must have that person's consent to this use and the rights to the material. You are responsible for what you send and what you generate from it. If we find or reasonably suspect a violation, we may suspend or disable your organisation's access.
Getting access
Both routes are switched on per organisation, by us. Ask support. Until they are on, a submit answers 403:
{"error": {"code": "Gateway.RealFacesNotEnabled", "message": "not enabled for your organisation; contact support"}}
The same 403 answers on /v1/modelark. Nothing is prepared and nothing is charged. The key must also be allowed
the model. If it is not, the answer is 403 with "this key is not granted access to this model".
Models and file limits
| model | resolutions | video length | reference images | reference clips | reference sounds |
|---|---|---|---|---|---|
bytedance/seedance-2.0 |
480p, 720p, 1080p, 4k | 4–15 s | up to 9 | up to 3 | up to 3 |
bytedance/seedance-2.0-fast |
480p, 720p | 4–15 s | up to 9 | up to 3 | up to 3 |
bytedance/seedance-2.0-mini |
480p, 720p | 4–15 s | up to 9 | up to 3 | up to 3 |
bytedance/seedance-2.5 |
480p, 720p, 1080p, 4k | 4–30 s | up to 30 | up to 10 | up to 10 |
bytedance/seedance-2.5-flash |
480p, 720p | 4–30 s | up to 10 | up to 5 | up to 5 |
The limits on each file are the generator's own:
| pictures (references and frames) | clips | sounds | |
|---|---|---|---|
| formats | jpeg, png, webp, bmp, tiff, gif, heic, heif | mp4, mov | wav, mp3 |
| size | under 30 MB | up to 200 MB | up to 15 MB |
| dimensions | 300–6000 px a side, aspect 0.4–2.5 | 300–6000 px a side, aspect 0.4–2.5, 407,696–8,295,044 pixels in all, 24–60 fps | — |
| length on the 2.0 models | — | 2–15 s each, 15 s in total | 2–15 s each, 15 s in total |
length on bytedance/seedance-2.5 |
— | 2–30 s each (4–30 s when the video edits the clip), 30 s in total | 2–30 s each, 30 s in total |
length on bytedance/seedance-2.5-flash |
— | 2–30 s each, 30 s in total | 2–30 s each, 30 s in total |
bytedance/seedance-2.5 and bytedance/seedance-2.5-flash also take sound alone. The 2.0 models need at least one picture or clip beside it.
Roles
Each part of content:
| what you send | part type |
role |
where the url goes |
|---|---|---|---|
| your prompt | text |
— | text |
| a picture of a character or an object | image_url |
reference_image |
image_url.url |
| a clip | video_url |
reference_video |
video_url.url |
| a voice or a sound | audio_url |
reference_audio |
audio_url.url |
| the first frame of the video | image_url |
first_frame |
image_url.url |
| the last frame of the video | image_url |
last_frame |
image_url.url |
A character, or several: reference_image
Send one picture per character, up to the model's ceiling for pictures. Name each character in the prompt by the picture's number: Image 1 is the first picture you sent, Image 2 the second (see Writing the prompt).
curl https://api.sociaro.com/v1/generations/refs \
-H "Authorization: Bearer $SOCIARO_API_KEY" -H "Content-Type: application/json" \
-d '{ "model": "bytedance/seedance-2.5",
"content": [
{ "type": "text", "text": "the man from @Image 1 and the woman from @Image 2 dance together in a sunlit kitchen" },
{ "type": "image_url", "image_url": {"url": "https://your-cdn.example.com/him.jpg"},
"role": "reference_image" },
{ "type": "image_url", "image_url": {"url": "https://your-cdn.example.com/her.jpg"},
"role": "reference_image" }
],
"resolution": "720p", "duration": 8 }'
A clip: reference_video
A clip carries motion, a camera move or a performance for the video to follow.
curl https://api.sociaro.com/v1/generations/refs \
-H "Authorization: Bearer $SOCIARO_API_KEY" -H "Content-Type: application/json" \
-d '{ "model": "bytedance/seedance-2.0",
"content": [
{ "type": "text", "text": "the man from [Image 1] performs the dance from [Video 1] on a rooftop at sunset" },
{ "type": "image_url", "image_url": {"url": "https://your-cdn.example.com/him.jpg"},
"role": "reference_image" },
{ "type": "video_url", "video_url": {"url": "https://your-cdn.example.com/dance.mp4"},
"role": "reference_video" }
],
"resolution": "720p", "duration": 5 }'
A voice: reference_audio
"generate_audio": true asks for a video with sound. Without the field the clip is silent, except when you send
your own audio (a reference_audio part) or the field omni_reference_task_type set to edit or extend (2.5 models only; a 2.0 edit or extension is asked for in the prompt and comes back silent unless you send "generate_audio": true or send your own audio (reference_audio), with which sound is on by default): then the generator's default (sound on) applies. On the 2.0 models a sound needs a picture or a clip beside
it; bytedance/seedance-2.5 and bytedance/seedance-2.5-flash also take a sound alone.
curl https://api.sociaro.com/v1/generations/refs \
-H "Authorization: Bearer $SOCIARO_API_KEY" -H "Content-Type: application/json" \
-d '{ "model": "bytedance/seedance-2.0",
"content": [
{ "type": "text", "text": "the woman from [Image 1] says good morning to the camera in the voice from [Audio 1]" },
{ "type": "image_url", "image_url": {"url": "https://your-cdn.example.com/her.jpg"},
"role": "reference_image" },
{ "type": "audio_url", "audio_url": {"url": "https://your-cdn.example.com/voice.mp3"},
"role": "reference_audio" }
],
"generate_audio": true, "resolution": "720p", "duration": 5 }'
The first frame: first_frame
The video starts on exactly this picture.
curl https://api.sociaro.com/v1/generations/refs \
-H "Authorization: Bearer $SOCIARO_API_KEY" -H "Content-Type: application/json" \
-d '{ "model": "bytedance/seedance-2.0",
"content": [
{ "type": "text", "text": "she turns towards the camera and smiles" },
{ "type": "image_url", "image_url": {"url": "https://your-cdn.example.com/first.jpg"},
"role": "first_frame" }
],
"resolution": "720p", "duration": 5 }'
First and last frame: first_frame + last_frame
The video starts on the first picture and ends on the second. If the two differ in shape, the last one is cropped to the first one's.
curl https://api.sociaro.com/v1/generations/refs \
-H "Authorization: Bearer $SOCIARO_API_KEY" -H "Content-Type: application/json" \
-d '{ "model": "bytedance/seedance-2.0",
"content": [
{ "type": "text", "text": "she walks from the door to the window" },
{ "type": "image_url", "image_url": {"url": "https://your-cdn.example.com/first.jpg"},
"role": "first_frame" },
{ "type": "image_url", "image_url": {"url": "https://your-cdn.example.com/last.jpg"},
"role": "last_frame" }
],
"resolution": "720p", "duration": 5 }'
Combining them
- Pictures, clips and sounds can be mixed in one request, up to each model's ceilings.
- Frames and references cannot be mixed. A request with
first_frameorlast_frameand anyreference_*is refused with a400before anything is prepared. Send the frames without references, or the references without frames. - At most one
first_frameand onelast_frameper request. - Every request needs at least one picture, clip, sound or frame. A prompt alone is refused with a
400.
Writing the prompt
Name each reference by its kind and its number: Image 1, Video 1, Audio 1. Image 1 is the first picture in
content order, Video 1 the first clip, Audio 1 the first sound. Each kind is counted on its own, from 1, so
Image 2 is the second picture you sent however many clips or sounds come between. This is the generator's own
rule. Say what each reference gives the video (a character, an object, a motion, a voice) and what it should not
take from it. The generator's examples write [Image 1] for the 2.0 models and @Image 1 for
bytedance/seedance-2.5:
The woman from [Image 1] performs the dance from [Video 1] on a rooftop and sings along to [Audio 1].
Our error messages number parts differently, among all your media together (see Links you send).
Edit or extend a clip (2.0)
The 2.0 models (bytedance/seedance-2.0, bytedance/seedance-2.0-fast, bytedance/seedance-2.0-mini) can edit a
clip or extend it. Neither has a field or a role of its own. You send the clip as a reference_video part, and the
generator works out from your prompt what to do with it. omni_reference_task_type exists on
bytedance/seedance-2.5 and bytedance/seedance-2.5-flash only; the 2.0 models accept it and ignore it.
Edit. Replace, add or remove something in the clip, or redraw part of it. Send the clip, and a
reference_image or reference_audio part for anything new it needs:
curl https://api.sociaro.com/v1/generations/refs \
-H "Authorization: Bearer $SOCIARO_API_KEY" -H "Content-Type: application/json" \
-d '{ "model": "bytedance/seedance-2.0",
"content": [
{ "type": "text", "text": "Replace the cat in [Video 1] with the lion from [Image 1]" },
{ "type": "image_url", "image_url": {"url": "https://your-cdn.example.com/lion.jpg"},
"role": "reference_image" },
{ "type": "video_url", "video_url": {"url": "https://your-cdn.example.com/cat.mp4"},
"role": "reference_video" }
],
"resolution": "720p", "ratio": "16:9", "duration": 5 }'
Extend. Continue one clip forward or backward, or send two or three clips and have the gaps between them filled:
curl https://api.sociaro.com/v1/generations/refs \
-H "Authorization: Bearer $SOCIARO_API_KEY" -H "Content-Type: application/json" \
-d '{ "model": "bytedance/seedance-2.0",
"content": [
{ "type": "text", "text": "The window in [Video 1] opens and the camera moves inside, transitioning into [Video 2], then into the painting, transitioning into [Video 3]" },
{ "type": "video_url", "video_url": {"url": "https://your-cdn.example.com/1.mp4"},
"role": "reference_video" },
{ "type": "video_url", "video_url": {"url": "https://your-cdn.example.com/2.mp4"},
"role": "reference_video" },
{ "type": "video_url", "video_url": {"url": "https://your-cdn.example.com/3.mp4"},
"role": "reference_video" }
],
"resolution": "720p", "ratio": "16:9", "duration": 8 }'
- Name each clip Video 1, Video 2 in
contentorder, and write Video 1, not reference Video 1: the generator's own guide warns that the word "reference" can make it treat the clip as something to imitate rather than the clip to edit. To add something, say what, where and when; to remove something, also say what must stay unchanged. - A forward or backward extension usually keeps only the tail of the original clip. If you want the original in the result, ask for it in the prompt, for example "… and then end with [Video 1]". Two or three clips come back with the originals and the new footage joined.
- Up to 3 clips, 2–15 s each and 15 s in total, with the file limits in
Models and file limits. A fourth clip is refused with a
400before anything is prepared. Each clip is prepared like any other file, so a large one takes longer (see Limits). durationis the length of the clip you get back, 4–15 s or-1. The generator does not say for these models whetherdurationmeans the length of the addition instead (ourbytedance/seedance-2.5page documents that reading for 2.5), nor whether an edit keeps the original clip's soundtrack.- Price. An edit or an extension is billed like any job with a video input: per token at the with-video rate,
with a minimum set by the
durationyou ask for. This route is priced separately from/v1/byteplus, so the minimums on the model pages are not the ones charged here; Logs in the console show what each job cost. With-1or nodurationthe minimum is the one for the length the generator chose, as it reports it for the finished clip (whole seconds, rounded down; 4 s if it reports none). A length given only in the prompt (--dur 8,--duration 8) counts as given, and that job's minimum is the 4 s one, as before. A render that meters more is charged what it meters.
Submit and poll
Submit, with Authorization: Bearer <your-api-key>:
curl https://api.sociaro.com/v1/generations/refs \
-H "Authorization: Bearer $SOCIARO_API_KEY" -H "Content-Type: application/json" \
-d '{ "model": "bytedance/seedance-2.0",
"content": [
{ "type": "text", "text": "the woman from [Image 1] walks along a rainy street at night, smiling" },
{ "type": "image_url", "image_url": {"url": "https://your-cdn.example.com/her.jpg"},
"role": "reference_image" }
],
"resolution": "720p", "duration": 5 }'
# -> { "job_id": "cgt-…", "status": "submitted" }
The answer comes once your files are prepared and the job is submitted: usually in a few seconds. Preparing your files stops at 40 s at the latest, and every submit is answered within about 100 s, so give your client a timeout of at least 100 s.
Poll the job until it is finished. Poll every 5–10 s:
curl https://api.sociaro.com/v1/generations/$JOB_ID -H "Authorization: Bearer $SOCIARO_API_KEY"
# -> { "job_id": "…", "status": "processing" }
# -> { "job_id": "…", "status": "completed", "model": "bytedance/seedance-2.0",
# "media_url": "https://api.sociaro.com/v1/media/<id>", … }
statusisprocessing,completedorfailed, and every one of them arrives with HTTP200.completedalways carriesmedia_url. Download it within the hour, with noAuthorizationheader, because the link is the credential. Copy the video into your own storage.- The answer also carries the generator's own fields, such as
usage. failedcarrieserror.code,error.messageand, when the generator gave one,error.provider_code.
The request
| field | type | what it is |
|---|---|---|
model |
string | one of the ids in Models and file limits |
content |
array | the parts (see Roles); at least one picture, clip, sound or frame |
resolution |
string | a tier from the models table; default 720p |
duration |
integer | seconds, within the model's video length, or -1 to let the generator choose; default 5 on the 2.0 models, -1 on bytedance/seedance-2.5 and bytedance/seedance-2.5-flash |
ratio |
string | 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 or adaptive (default); on bytedance/seedance-2.5 and bytedance/seedance-2.5-flash a request with frames keeps the first frame's shape, so only adaptive applies there |
generate_audio |
boolean | let the generator compose a soundtrack; off unless you send true, on by default with reference_audio or omni_reference_task_type edit/extend (2.5 only; a 2.0 edit or extension set in the prompt is silent unless true or with reference_audio) |
watermark |
boolean | default false on this route |
seed |
integer | similar, not identical, results for the same seed |
return_last_frame |
boolean | the closing still beside the clip |
output_format |
string | mp4; mov on bytedance/seedance-2.5 and bytedance/seedance-2.5-flash only |
bitrate_mode |
string | standard or high |
omni_reference_task_type |
string | bytedance/seedance-2.5 and bytedance/seedance-2.5-flash only: auto, reference, edit or extend |
execution_expires_after |
integer | seconds, 3600–259200 (default 172800): a task not finished by then is marked expired, and an expired job is not charged |
safety_identifier |
string | 1–64 characters: a fixed id for your end user, which the generator uses to spot policy abuse; we send a per-organisation pseudonym of your value, never the value itself |
user |
string | your own end-user id, recorded with the job: at most 128 characters, no control characters |
An unknown field is refused with a 400 naming it. callback_url is refused: poll for the result. Drafts are not
offered on this route: draft (other than false) and a draft_task part are refused with a 400
Gateway.InvalidRequest, "drafts are not offered on this route", before anything is prepared or charged.
A job on this route is priced separately from the same job on /v1/byteplus or /v2/jobs.
Special rates may be available — contact your account manager.
Links you send
Send public https links. Signed links work if they stay valid until your submit has been answered.
- Do not send
http, inline base64, or a private or internal address. - A server-side fetch is refused by firewalls, bot filters and links that expire within seconds. Those come back as a
400withGateway.InputDownloadFailed, naming the part, for example reference image 2. That number is the part's position among ALL the media you sent, incontentorder, so reference image 2 is the second media part, which is a picture (the same rule as on the other reference routes).
The vendor-format route: /v1/modelark
If you call Seedance in the vendor's own request format, the same preparation of every media role is available at
https://api.sociaro.com/v1/modelark — submit POST /contents/generations/tasks, poll
GET /contents/generations/tasks/{id}. Send plain https links for first and last frames, reference
images, reference videos and reference audio; nothing else changes in the request. It needs the same access as
/v1/generations/refs: until your organisation has it, a submit answers 403 with Gateway.RealFacesNotEnabled
(see Getting access). A task that sends at least one of those links, or renders the final from a
draft that sent one, is priced separately from the same task on /v1/byteplus, as on /v1/generations/refs; any
other task costs the same as on /v1/byteplus.
The submit accepts the task and returns its id at once with status: "queued". Poll with that id: while
queued the task can still fail — with Gateway.InputUrlInvalid or Gateway.InputDownloadFailed (fix the
link), Gateway.InvalidRequest (fix the file), Gateway.InputPreparationFailed (the message names the file by its
role and position and gives the generator's reason: replace or re-encode it), Gateway.InputPreparationTimeout or
Gateway.InputPreparationBusy (temporary: submit again), none of which charges anything and each of which is listed
in your Logs as a failed request — and a refusal by the generator arrives
the same way with its own code and message. After that the poll answers the generator's statuses, and on
succeeded content.video_url is a permanent link. The full table is in the
Generations API guide.
Errors
This section and Limits below are about POST /v1/generations/refs. On /v1/modelark the preparation
failures arrive on the poll (see the vendor-format route), and its other
statuses, including 402 for a spent balance, are in the Generations API guide.
On the submit
| status | error.code |
what to do |
|---|---|---|
400 |
Gateway.InputUrlInvalid |
the link is not a public https url: fix it |
400 |
Gateway.InputDownloadFailed |
we could not fetch that link: make it reachable from the public internet |
400 |
Gateway.InvalidRequest |
the file itself was refused (too short, too small); the message says why |
400 |
— | the request is wrong (frames with references, an unknown field, a missing part); the message says what |
400 |
Gateway.InvalidRequest |
also: a draft (draft, or a draft_task part); drafts are not offered on this route |
401 |
— | the key is missing or wrong |
403 |
Gateway.RealFacesNotEnabled |
these routes are not switched on for your organisation: contact support |
413 |
— | the body is over 256 KiB: send media as links, never inline |
422 |
Gateway.InputPreparationFailed |
one file could not be prepared; the message names it by its position among your media and its role, for example "the reference image at position 2 could not be prepared: …", with the reason, and provider_code carries the generator's code when it gave one. Replace or re-encode that file |
429 |
— | out of balance or too many requests; the message says which |
503 |
Gateway.InputPreparationBusy, Gateway.InputPreparationTimeout |
preparation is busy, or a file did not become usable in time (the message names it by role and position): retry after Retry-After seconds |
503 |
Gateway.UpstreamUnavailable |
the generator is unavailable to us (here: its answer could not be read). It comes WITHOUT Retry-After: the outcome at the generator is unknown, so do not resubmit automatically. You hold no job id and are not charged for it |
503 |
— | temporarily unavailable; the message says why: retry later |
| the generator's | the generator's | it refused the request itself; its own code and message, vendor names replaced (below) |
None of these is charged to you. A refusal while your files are prepared (the Gateway.Input… codes, and
Gateway.InvalidRequest for a refused file) is listed in your Logs as a failed request.
Refusals by the generator
A refusal of the request itself, such as an input it will not take, comes back on the submit at once, with the
generator's status, error.code and message, and nothing is charged. A refusal after rendering arrives on the poll as
status: "failed", with the generator's reason and provider_code, for example:
{"error": {"code": "provider_failed",
"provider_code": "OutputAudioSensitiveContentDetected.PolicyViolation",
"message": "The request failed because the output audio may be related to copyright restrictions."}}
A soundtrack the generator composed is checked after the video renders. Sound is off unless you send
"generate_audio": true (on by default with reference_audio or omni_reference_task_type edit/extend on 2.5; send false there for a
silent clip; a 2.0 edit or extension asked for in the prompt is silent unless you send true or send your own audio (reference_audio), with which sound is on by default), so a silent job never meets that failure. A failed job is not charged, and neither is a refused submit.
On the ordinary Seedance route
On the ordinary Seedance route the generator checks each reference itself and may refuse one before anything is generated. A picture reads like this, and a clip is refused the same way:
{"error": {"code": "InputImageSensitiveContentDetected.PrivacyInformation",
"message": "The request failed because the input image 'content[1]' may contain real person."}}
That refusal is what the two routes on this page are for: they prepare every file before the generation is submitted.
When the answer is an HTML page, not JSON
A 502, 504 or 524 with an HTML body is our edge (Cloudflare), not the gateway: it replaces an error body from
us, or (524) cut a request held for about 120 s.
- On the submit you hold no job id. Resubmit only once your Logs show no job for the first attempt: rarely it was accepted, and then it is charged.
- On a poll, nothing changed: poll the same id again.
Limits
- Body: 256 KiB. Send media as links.
- Preparation: 120 file uploads a minute across the gateway; up to 12 files of one request are prepared at once. There is no per-key limit
on this door; under load you get
503Gateway.InputPreparationBusywithRetry-After. - Time: preparing your files stops at 40 s at the latest (a
503withRetry-After), and every submit is answered within about 100 s.