Sociaro

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 poll GET /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_frame or last_frame and any reference_* is refused with a 400 before anything is prepared. Send the frames without references, or the references without frames.
  • At most one first_frame and one last_frame per 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 content order, 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 400 before anything is prepared. Each clip is prepared like any other file, so a large one takes longer (see Limits).
  • duration is the length of the clip you get back, 4–15 s or -1. The generator does not say for these models whether duration means the length of the addition instead (our bytedance/seedance-2.5 page 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 duration you 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 -1 or no duration the 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>", … }
  • status is processing, completed or failed, and every one of them arrives with HTTP 200.
  • completed always carries media_url. Download it within the hour, with no Authorization header, 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.
  • failed carries error.code, error.message and, 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.

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 400 with Gateway.InputDownloadFailed, naming the part, for example reference image 2. That number is the part's position among ALL the media you sent, in content order, 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 503 Gateway.InputPreparationBusy with Retry-After.
  • Time: preparing your files stops at 40 s at the latest (a 503 with Retry-After), and every submit is answered within about 100 s.