Seedance 1.5 Pro

bytedance/seedance-1-5-pro — a video model by ByteDance. Call it through the gateway’s standard OpenAI-compatible door using the catalog slug; the full parameter schema is reproduced in full below.


Catalog slug	`bytedance/seedance-1-5-pro`
Kind	`video`
Vendor	ByteDance

How to call

Through the Sociaro SDK / OpenAI-compatible door

Video generation is asynchronous (create → poll → result). The SDK’s video.generate drives the whole cycle and blocks until the job reaches a terminal state:

from sociaro_ai import Sociaro

client = Sociaro(api_key="gw_live_...")

result = client.video.generate(
    model="bytedance/seedance-1-5-pro",
    prompt="a timelapse of a blooming flower",
    # resolution / duration / audio … — see the schema below
)
print(result.url)

For a non-blocking handle use job = client.video.submit(model="bytedance/seedance-1-5-pro", …) then job.result(). Raw door: POST https://api.sociaro.com/v1/videos (create), then poll — see async jobs and media doors.

Parameters — full schema

The complete, one-to-one API schema for this model, transcribed from the official source. Nothing omitted. Examples in the schema may use a representative model of the family — for this model use the slug bytedance/seedance-1-5-pro as shown in How to call above.

Coverage map (which model is covered by which API behaviour)

ALL models in this family are invoked through ONE asynchronous video-generation door (create → poll). The schema is identical; models differ only in WHICH parameter values / scenarios they accept.

Covered catalog slugs (passed in the model field):

bytedance/seedance-1-0-pro
bytedance/seedance-1-0-pro-fast
bytedance/seedance-1-5-pro
bytedance/dreamina-seedance-2-0
bytedance/dreamina-seedance-2-0-fast
bytedance/dreamina-seedance-2-0-mini (at research date: not yet available via the API — gate until API-live)

Critical per-model differences (capability matrix)

”—” = not supported.

Capability / scenario	1.0 Pro	1.0 Pro Fast	1.5 Pro	2.0	2.0 Fast
Text-to-video (t2v)	yes	yes	yes	yes	yes
i2v — first frame	yes	yes	yes	yes	yes
i2v — first + last frames	yes	—	yes	yes	yes
Multimodal reference-to-video (image)	—	—	—	yes	yes
Video input (`video_url`)	—	—	—	yes	yes
Audio input (`audio_url`)	—	—	—	yes	yes
Audio-video output (`generate_audio`)	—	—	yes	yes	yes
Video Editing / Video Extension	—	—	yes	yes	yes
Draft mode (`draft` / `draft_task`)	—	—	yes	yes*	—
`return_last_frame`	yes	yes	yes	yes	yes
`priority` (0–9)	—	—	—	yes	—
`frames`	yes	yes	—	—	—
`camera_fixed`	yes	yes	yes	—	—
`service_tier` (default/flex)	yes	yes	yes	— (online only, ignored)	— (online only, ignored)
`1080p` resolution	yes	yes	yes	yes	—

* Draft mode is documented as supported by Seedance 1.5 Pro (the draft_task / draft flow); the tutorial capability matrix also lists “Draft Mode” under Dreamina Seedance 2.0, but the API reference restricts the draft boolean and the draft_task content type to Seedance 1.5 Pro only (“This feature is only supported by seedance 1.5 pro”). Treat draft/draft_task as 1.5 Pro only for strict API validation.

Other per-model rules (defaults & ranges — see parameter tables for exact values):

resolution default: 720p for 2.0 series & 1.5 Pro; 1080p for 1.0 Pro & 1.0 Pro Fast. 1080p not supported by 2.0 Fast. Draft mode (1.5 Pro) forces 480p.
ratio default: adaptive for 2.0 series & 1.5 Pro; for other models t2v=16:9, i2v=adaptive. adaptive for non-2.0/1.5 models only works for image-to-video.
duration range: 1.0 Pro / 1.0 Pro Fast [2,12]; 1.5 Pro [4,12] or -1; 2.0 series [4,15] or -1. -1 (intelligent) is 2.0 series & 1.5 Pro only.
prompt languages: all models support English; 2.0 & 2.0 Fast additionally support Japanese, Indonesian, Spanish, Portuguese.
image formats: .jpeg .png .webp .bmp .tiff .gif; .heic .heif additionally for 1.5 Pro & 2.0 series.
face safety (2.0 series): does NOT accept direct upload of reference images/videos containing real human faces; use trusted outputs (face videos generated by 2.0 series under your account within 30 days), preset digital characters, or authorized real-person assets (asset://<ID>).
billing: video billed on completion_tokens (input always 0 ⇒ total_tokens = completion_tokens). Seedance 2.0 series has a minimum token-usage floor: if actual usage < the floor, usage.completion_tokens returns the floor and the floor is billed. duration:-1 affects cost (model picks length). flex = 50% of default price.
retention: task ID — 7 days from created_at; video_url and last_frame_url — 24 hours (save immediately).

Endpoints (standard async video door)

Operation	Method + path	Through the gateway door?
Create a video generation task	`POST https://api.sociaro.com/v1/videos`	Yes
Retrieve a video generation task	`GET https://api.sociaro.com/v1/videos/{id}`	Yes
List video generation tasks	`GET https://api.sociaro.com/v1/videos`	No — native Ark API only
Cancel or delete a task	`DELETE https://api.sociaro.com/v1/videos/{id}`	No — native Ark API only

Auth: header Authorization: Bearer $SOCIARO_API_KEY.
Content-Type: application/json.
Pass a Seedance catalog slug in the model field (e.g. bytedance/seedance-1-5-pro). The gateway routes the request to ByteDance’s video API on your behalf.
This is an asynchronous, two-step pattern: Create returns only { "id": "cgt-..." }; the real result (video_url, usage, actual duration/ratio/resolution) appears only via Retrieve or callback. Critical for a transparent-mode gateway.
Only Create and Retrieve are gateway doors. The gateway registers POST /v1/videos and GET /v1/videos/{id} only; GET /v1/videos (LIST) and DELETE /v1/videos/{id} (CANCEL/DELETE) are not implemented as doors: GET /v1/videos returns 404 Not Found (unregistered path), DELETE /v1/videos/{id} returns 405 Method Not Allowed. The schemas for LIST and CANCEL below describe ByteDance’s native Ark API and apply only when calling Ark directly. To list your async jobs through the gateway, use GET /gw/async (the gateway’s own job ledger) instead.

CREATE — `POST /v1/videos`

Request body shape

{
  "model": "bytedance/seedance-1-5-pro",       // REQUIRED — catalog slug
  "content": [ /* array of: text / image_url / video_url / audio_url / draft_task objects */ ], // REQUIRED
  "callback_url": "https://...",               // optional
  "return_last_frame": false,                  // optional
  "service_tier": "default",                   // optional (default | flex); ignored by 2.0 series
  "execution_expires_after": 172800,           // optional, seconds [3600, 259200]
  "generate_audio": true,                      // optional (2.0 series & 1.5 Pro only)
  "draft": false,                              // optional (Seedance 1.5 Pro only)
  "safety_identifier": "<hash>",               // optional, <=64 chars
  "priority": 0,                               // optional, 0-9 (Seedance 2.0 only)
  "resolution": "720p",                        // optional
  "ratio": "16:9",                             // optional
  "duration": 5,                               // optional (use duration OR frames)
  "frames": 29,                                // optional (NOT for 2.0 series / 1.5 Pro)
  "seed": -1,                                  // optional
  "camera_fixed": false,                       // optional (NOT for 2.0 series; NOT for reference-to-image)
  "watermark": false                           // optional
}

Two ways to set resolution / ratio / duration / frames / seed / camera_fixed / watermark:

New method (recommended): separate top-level fields, strict validation (bad value → error). Abbreviations are NOT supported in the new method (write parameters in full).

Legacy method: append --[parameter] to the end of content.text, loose validation (bad value → silently substitutes default, no error). All models still support the legacy method. Suffix forms: --rs 720p --rt 16:9 --dur 5 --seed 11 --cf false --wm true or full names: --resolution 720p --ratio 16:9 --duration 5 --seed 11 --camerafixed false --watermark true

Different models support different parameters/values. If a parameter/option is not supported by the selected model, it is either ignored or an error is thrown (new method → error; legacy method → default).

CREATE — all top-level body parameters

Parameter	Type	Required	Default	Allowed values / range	Description
`model`	string	Required	—	catalog slug	The catalog slug of the model to call, e.g. `bytedance/seedance-1-5-pro`.
`content`	object[]	Required	—	array of text / image_url / video_url / audio_url / draft_task objects	References for generation. See content-item tables below.
`callback_url`	string	optional	—	URL	Callback address. On task status change the service sends a POST whose body is identical to the Retrieve response. Callback statuses: `queued`, `running`, `succeeded`, `failed`, `expired`. On delivery failure (no success confirmation within 5 s), retried up to 3 times.
`return_last_frame`	boolean	optional	`false`	`true` / `false`	`true` → return the last frame of the video (PNG, same width/height as the video, no watermark) via Retrieve (`content.last_frame_url`). Used to chain consecutive videos (last frame → first frame of next).
`service_tier`	string	optional	`default`	`default`, `flex`	Processing tier. `default` = online inference (lower RPM/concurrency). `flex` = offline inference (higher TPD, 50% of online price, higher latency). Cannot be changed after submit. Seedance 2.0 series supports only online inference and does NOT support this parameter.
`execution_expires_after`	integer	optional	`172800`	`[3600, 259200]` seconds	Task timeout threshold measured from `created_at`. Default 172800 s (48 h). After this, task → `expired`. Recommended to set regardless of `service_tier`.
`generate_audio`	boolean	optional	`true`	`true` / `false`	Only Seedance 2.0 series & Seedance 1.5 Pro. `true` → video with synchronized audio (voice/SFX/BGM auto-generated from prompt & visuals; put dialogue in double quotes for best results). `false` → silent video. All audio-videos are mono regardless of input channel count.
`draft`	boolean	optional	`false`	`true` / `false`	Only Seedance 1.5 Pro. `true` → draft mode (preview, fewer tokens / cheaper; generated at 480p — other resolutions error; `return_last_frame` and offline inference NOT supported).
`safety_identifier`	string	optional	—	English string, ≤ 64 chars, fixed & unique per user	End-user identifier for policy-violation detection. Recommended: hash of username / user ID / email. Returned unchanged in Retrieve/List.
`priority`	integer	optional	`0`	`0`–`9` (larger = higher)	Only Seedance 2.0. Queue priority within a single Endpoint. Default FIFO; higher priority inserts the request ahead of all lower-priority queued requests under the same Endpoint. Does NOT interrupt running tasks; same-priority requests stay FIFO; affects only the same Endpoint. Not supported when `service_tier=flex`.
`resolution`	string	optional	2.0 series & 1.5 Pro: `720p`; 1.0 Pro & 1.0 Pro Fast: `1080p`	`480p`, `720p`, `1080p`	Video resolution. `1080p` not supported by Seedance 2.0 Fast. Draft mode (1.5 Pro) forces `480p`.
`ratio`	string	optional	2.0 series & 1.5 Pro: `adaptive`; other models: t2v `16:9`, i2v `adaptive`	`16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `adaptive`	Aspect ratio. `adaptive` = model auto-selects (t2v → from prompt; first/last-frame → from uploaded first frame; multimodal → from prompt intent, else from first uploaded media, priority video > image). Actual value returned in Retrieve (`ratio`). `adaptive` supported by 2.0 series & 1.5 Pro; for other models only for image-to-video. Pixel sizes per ratio×resolution: see table below.
`duration`	integer	optional	`5`	1.0 Pro / 1.0 Pro Fast: `[2,12]` s; 1.5 Pro: `[4,12]` or `-1`; 2.0 series: `[4,15]` or `-1`	Video length in integer seconds. Specify `duration` OR `frames`; `frames` takes precedence. `-1` (2.0 series & 1.5 Pro only) = intelligent: model picks integer length within range (affects billing). Actual length returned in Retrieve.
`frames`	integer	optional	—	integers in `[29, 289]` matching the format `25 + 4n` (n = positive integer); frames = duration × 24	NOT supported by Seedance 2.0 series & Seedance 1.5 Pro. Frame count (for fractional seconds). Specify `duration` OR `frames`; `frames` takes precedence. Formula: frames = duration × frame rate (24). Example: 2.4 s → 2.4×24 = 57.6 → nearest `25+4n` = 57 → actual 57/24 = 2.375 s.
`seed`	integer	optional	`-1`	integer `[-1, 2^32-1]`	Randomness seed. Different seed (or `-1` / unset → random) → different results; same seed → similar (not guaranteed identical) results.
`camera_fixed`	boolean	optional	`false`	`true` / `false`	Not supported in reference-to-image scenarios, and not currently supported by Seedance 2.0 series. `true` → the model appends a fixed-camera instruction to the prompt (result not guaranteed).
`watermark`	boolean	optional	`false`	`true` / `false`	`true` → “AI Generated” watermark in the lower-right corner. `false` → no watermark.

CREATE — `content[]` item types

Supported content combinations (at least one of text/image/video; audio can NOT be the sole input — at least one reference video or image is required):

Text
Text (optional) + image
Text (optional) + video
Text (optional) + image + audio
Text (optional) + image + video
Text (optional) + video + audio
Text (optional) + image + video + audio
Sample/Draft task ID

The three image scenarios are mutually exclusive and cannot be mixed: i2v first-frame, i2v first-and-last-frames, multimodal reference. (For multimodal reference you may specify reference images as first/last frame in the prompt to approximate a “first/last frame + references” effect; for strict first/last-frame match use the i2v first-and-last-frames scenario with role = first_frame / last_frame.)

A) Text

Field	Type	Required	Allowed values	Description
`content[].type`	string	Required	`"text"`	Content type.
`content[].text`	string	Required	string	Text prompt describing the expected video. Languages: all models support English; 2.0 & 2.0 Fast additionally Japanese, Indonesian, Spanish, Portuguese. Recommended length < 1000 words (overly long text scatters focus). Legacy `--[param]` suffixes may be appended here.

B) Image (`image_url`)

Field	Type	Required	Allowed values	Description
`content[].type`	string	Required	`"image_url"`	Supports image URL or image Base64.
`content[].image_url`	object	Required	—	Input image object.
`content[].image_url.url`	string	Required	URL / Base64 / asset ID	Public URL; OR Base64 `data:image/<format>;base64,<...>` (format lowercase, e.g. `data:image/png;base64,{base64_image}`); OR `asset://<ASSET_ID>` (from Elements & Digital Characters Library).
`content[].role`	string	Required under certain conditions	`first_frame`, `last_frame`, `reference_image`	Position/purpose of the image — rules below.

Single-image requirements:

Formats: .jpeg, .png, .webp, .bmp, .tiff, .gif (plus .heic, .heif for Seedance 1.5 Pro & 2.0 series).
Aspect ratio (w/h): (0.4, 2.5).
Width & height: (300, 6000) px.
Size: single image < 30 MB; total request body ≤ 64 MB; do not Base64-encode large files.
Number of images: i2v first frame = 1; i2v first+last = 2; 2.0 series multimodal reference = 1–9.

role rules and image count:

i2v — first frame: all models; 1 image; role=first_frame or blank.
i2v — first and last frames: Seedance 2.0 & 2.0 Fast, 1.5 Pro, 1.0 Pro; 2 images; role required (first_frame / last_frame). The two frames may be the same image; if aspect ratios differ, the first frame takes precedence and the last frame is auto cropped (centered).
Multimodal reference images: Seedance 2.0 series only; 1–9 images; role=reference_image for each.

C) Video (`video_url`) — new; Seedance 2.0 series only

Field	Type	Required	Allowed values	Description
`content[].type`	string	Required	`"video_url"`	Video URL only.
`content[].video_url`	object	Required	—	Input video object.
`content[].video_url.url`	string	Required	URL / asset ID	Public video URL (only video URLs supported); OR `asset://<ASSET_ID>` (digital character library).
`content[].role`	string	Conditionally required	`reference_video`	Currently only `reference_video`.

Video input requirements:

Formats: mp4, mov. Containers/codecs: MP4 (.mp4, video/mp4) and QuickTime (.mov, video/quicktime); video codecs H.264/AVC, H.265/HEVC; audio codecs AAC, MP3.
Resolution: 480p / 720p / 1080p.
Duration: each video [2, 15] s; up to 3 reference videos; total of all videos ≤ 15 s.
Aspect ratio (w/h): [0.4, 2.5].
Width & height: [300, 6000] px.
Total pixels (w×h): [640×640 = 409600, 2206×946 = 2086876].
Size: each video ≤ 50 MB.
Frame rate (FPS): [24, 60].
The service trusts face-containing videos generated by Seedance 2.0 series models under your account within the past 30 days.

D) Audio (`audio_url`) — new; Seedance 2.0 series only

Field	Type	Required	Allowed values	Description
`content[].type`	string	Required	`"audio_url"`	Supports audio URL or audio Base64.
`content[].audio_url`	object	Required	—	Input audio object.
`content[].audio_url.url`	string	Required	URL / Base64 / asset ID	Public URL; OR Base64 `data:audio/<format>;base64,<...>` (format lowercase, e.g. `data:audio/wav;base64,{base64_audio}`); OR `asset://<ASSET_ID>`.
`content[].role`	string	Conditionally required	`reference_audio`	Currently only `reference_audio`.

Audio input requirements:

Formats: wav, mp3.
Duration: each audio [2, 15] s; up to 3 reference audio segments; total of all audio ≤ 15 s.
Size: each audio ≤ 15 MB; total request body ≤ 64 MB; do not Base64-encode large files.
Audio can NOT be input alone — at least one reference video or image is required.

E) Sample / Draft task (`draft_task`) — Seedance 1.5 Pro only

Field	Type	Required	Allowed values	Description
`content[].type`	string	Required	`"draft_task"`	Generate an official video from a draft.
`content[].draft_task`	object	Required	—	Draft task input.
`content[].draft_task.id`	string	Required	draft task ID	Draft video task ID. The model auto-reuses the draft’s inputs (`model`, `content.text`, `content.image_url`, `generate_audio`, `seed`, `ratio`, `duration`, `camera_fixed`); other parameters can be set manually, else model defaults apply. Two-step flow: (1) create a draft (`draft:true`); (2) after confirming the draft, create the final video using the draft task ID.

Pixel dimensions by resolution × ratio

Resolution	Ratio	W×H (Seedance 1.0 series)	W×H (Seedance 1.5 Pro / 2.0 series)
480p	16:9	864×480	864×496
480p	4:3	736×544	752×560
480p	1:1	640×640	640×640
480p	3:4	544×736	560×752
480p	9:16	480×864	496×864
480p	21:9	960×416	992×432
720p	16:9	1248×704	1280×720
720p	4:3	1120×832	1112×834
720p	1:1	960×960	960×960
720p	3:4	832×1120	834×1112
720p	9:16	704×1248	720×1280
720p	21:9	1504×640	1470×630
1080p (not for 2.0 Fast)	16:9	1920×1088	1920×1080
1080p	4:3	1664×1248	1664×1248
1080p	1:1	1440×1440	1440×1440
1080p	3:4	1248×1664	1248×1664
1080p	9:16	1088×1920	1080×1920
1080p	21:9	2176×928	2206×946

For image-to-video, when the selected video aspect ratio differs from the uploaded image’s ratio, the model crops the image centered.

CREATE — response

Returns only the task ID (asynchronous):

{ "id": "cgt-2026******-****" }

Field	Type	Description
`id`	string	Video generation task ID. Stored for 7 days from `created_at`, then cleared. When `draft:true` → draft task ID; when `draft:false` → normal task ID. Poll via Retrieve.

RETRIEVE — `GET /v1/videos/{id}`

Path parameter

Parameter	Type	Required	Description
`id`	string	required	ID of the video generation task to query.

Response shape

{
  "id": "cgt-2025******-****",
  "model": "bytedance/dreamina-seedance-2-0",     // catalog slug
  "status": "succeeded",
  "error": null,                                // or { "code": "...", "message": "..." }
  "content": {
    "video_url": "https://.../****",
    "last_frame_url": "https://.../****"        // only if return_last_frame:true was set
  },
  "usage": { "completion_tokens": 108900, "total_tokens": 108900 },
  "created_at": 1743414619,
  "updated_at": 1743414673,
  "seed": 10,
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,                                // duration OR frames (whichever was set)
  "frames": 29,                                 // duration OR frames
  "framespersecond": 24,
  "generate_audio": true,
  "safety_identifier": "...",
  "priority": 0,
  "draft": false,                               // only Seedance 1.5 Pro
  "draft_task_id": "...",                        // when generating from a draft
  "service_tier": "default",
  "execution_expires_after": 172800
}

RETRIEVE — response parameters

Field	Type	Description
`id`	string	Task ID.
`model`	string	Model name and version (Model name-Version).
`status`	string	`queued`, `running`, `cancelled` (only `queued` tasks can be cancelled), `succeeded`, `failed`, `expired`.
`error`	object \| null	`null` on success; otherwise `{code, message}`. See Error codes.
`error.code`	string	Error code.
`error.message`	string	Error message.
`created_at`	integer	Task creation time, Unix seconds.
`updated_at`	integer	Last update time, Unix seconds.
`content`	object	Output after completion.
`content.video_url`	string	Output video URL. Deleted after 24 h — save promptly.
`content.last_frame_url`	string	Last-frame URL (PNG; 24 h validity). Returned only if `return_last_frame:true` was set on create.
`seed`	integer	Seed used for this request.
`resolution`	string	Generated video resolution.
`ratio`	string	Actual aspect ratio (important when `adaptive` was requested).
`duration`	integer	Length in seconds. Returned only if `frames` was NOT specified on create.
`frames`	integer	Frame count. Returned only if `frames` WAS specified on create.
`framespersecond`	integer	Frame rate of the generated video.
`generate_audio`	boolean	Whether the video has synchronized audio (only 2.0 series & 1.5 Pro return this).
`safety_identifier`	string	End-user identifier (returned unchanged if it was set on create).
`priority`	integer	Execution priority of the request.
`draft`	boolean	Whether the output is a draft video (only Seedance 1.5 Pro returns this).
`draft_task_id`	string	Draft video task ID (returned when generating an official video from a draft).
`service_tier`	string	Service tier actually used to process the task.
`execution_expires_after`	integer	Task expiration threshold, seconds.
`usage`	object	Token usage.
`usage.completion_tokens`	integer	Tokens consumed for the video output. (See List page note: 2.0 series enforces a minimum-token floor.)
`usage.total_tokens`	integer	Total. For video models input tokens are always 0 ⇒ `total_tokens = completion_tokens`.

LIST — `GET /v1/videos` (native Ark API only — not a gateway door)

Not available through the gateway. GET /v1/videos is not registered as a door and returns 404 Not Found (the path does not match the registered /v1/videos/{id} route). The schema below is ByteDance’s native Ark API and applies only when calling Ark directly. Through the gateway, list your async jobs with GET /gw/async.

GET /v1/videos?page_num={}&page_size={}&filter.status={}&filter.task_ids={}&filter.model={}&filter.service_tier={}

Note: Only the last 7 days of historical data can be queried. Time is always UTC; the returned 7-day window is based on the actual request time T (to the second), interval [T-7d, T).

LIST — request parameters (all are query-string parameters)

Parameter	Type	Required	Default	Range / values	Description
`page_num`	integer / null	optional	—	`[1, 500]`	Page number of returned results.
`page_size`	integer / null	optional	—	`[1, 500]`	Number of results per page.
`filter.status`	string / null	optional	—	`queued`, `running`, `cancelled`, `succeeded`, `failed`	Filter by task status.
`filter.task_ids`	string[] / null	optional	—	task IDs	Exact match, batch supported. Multiple IDs joined with `&`, e.g. `filter.task_ids=id1&filter.task_ids=id2`.
`filter.model`	string / null	optional	—	catalog slug	Exact match, only one value. Passing a catalog slug returns tasks created for that model.
`filter.service_tier`	string / null	optional (new)	`default`	`default`, `flex`	Service tier used for task processing. `default` = online; `flex` = offline.

LIST — response shape

{
  "total": 3,
  "items": [
    {
      "id": "cgt-2025******-****",
      "model": "bytedance/dreamina-seedance-2-0",
      "status": "succeeded",
      "content": { "video_url": "https://.../****.mp4?X-Tos-..." },
      "usage": { "completion_tokens": 108900, "total_tokens": 108900 },
      "created_at": 1743414619,
      "updated_at": 1743414673,
      "seed": 10,
      "resolution": "720p",
      "ratio": "16:9",
      "duration": 5,
      "framespersecond": 24,
      "service_tier": "default",
      "execution_expires_after": 172800,
      "generate_audio": true,
      "draft": false,
      "priority": 0
    }
    // ...
  ]
}

LIST — response parameters

Field	Type	Description
`total`	integer	Number of tasks matching the filter conditions.
`items`	object[]	List of matching tasks. Scope = the tasks created with your API key.
`items[].id`	string	Task ID.
`items[].model`	string	Model name and version (model name-version).
`items[].status`	string	`queued`, `running`, `cancelled` (only `queued` can be cancelled), `succeeded`, `failed`, `expired`.
`items[].error`	object / null	`null` on success; otherwise `{code, message}`. See Error codes.
`items[].error.code`	string	Error code.
`items[].error.message`	string	Error message.
`items[].created_at`	integer	Creation time, Unix seconds.
`items[].updated_at`	integer	Last status-update time, Unix seconds.
`items[].content`	object	Output when the task is complete (download URL of the generated video).
`items[].content.video_url`	string	Generated video URL. Deleted after 24 h — save promptly.
`items[].content.last_frame_url`	string	Last-frame URL (24 h). Returned only if `return_last_frame:true` was set on create.
`items[].seed`	integer	Seed used.
`items[].resolution`	string	Resolution.
`items[].ratio`	string	Aspect ratio.
`items[].duration`	integer	Duration (seconds). Returned only if `frames` was NOT specified on create.
`items[].frames`	integer	Frame count. Returned only if `frames` WAS specified on create.
`items[].framespersecond`	integer	Frame rate.
`items[].generate_audio`	boolean	Whether the video has synchronized audio (only 2.0 series & 1.5 Pro return this).
`items[].safety_identifier`	string	End-user identifier (returned unchanged if set on create).
`items[].priority`	integer	Execution priority.
`items[].draft`	boolean	Whether the output is a draft video (only Seedance 1.5 Pro returns this).
`items[].draft_task_id`	string	Draft video task ID (returned when generating an official video from a draft).
`items[].service_tier`	string	Service tier actually used.
`items[].execution_expires_after`	integer	Task timeout threshold, seconds.
`items[].usage`	object	Token usage.
`items[].usage.completion_tokens`	integer	Tokens consumed for the video output (basis for billing reconciliation). Seedance 2.0 series has a minimum-token-usage floor: if actual usage < the floor, this returns the floor, which is billed.
`items[].usage.total_tokens`	integer	Total. Input tokens are 0 ⇒ `total_tokens = completion_tokens`.

CANCEL / DELETE — `DELETE /v1/videos/{id}` (native Ark API only — not a gateway door)

Not available through the gateway. DELETE /v1/videos/{id} is not registered as a door and returns 405 Method Not Allowed. The behaviour below is ByteDance’s native Ark API and applies only when calling Ark directly.

Cancels a queued task, or deletes a task record.

Path parameter

Parameter	Type	Required	Description
`id`	string	required	ID of the task to cancel or delete.

Behaviour by task status

Task status	Deletable?	Operation	Post-DELETE status
`queued`	Yes	Removed from queue; status updated to `cancelled`.	`cancelled`
`running`	No	—	—
`succeeded`	Yes	Task record deleted; no longer queryable.	—
`failed`	Yes	Task record deleted; no longer queryable.	—
`cancelled`	No	—	—
`expired`	Yes	Task record deleted; no longer queryable.	—

Response

No response parameters. On success returns an empty object:

{}

Examples

Minimal (text-to-video)

Create:

curl https://api.sociaro.com/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SOCIARO_API_KEY" \
  -d '{
    "model": "bytedance/seedance-1-0-pro",
    "content": [ { "type": "text", "text": "A kitten yawns at the camera" } ]
  }'

→ { "id": "cgt-2026******-****" }

Retrieve:

curl -X GET https://api.sociaro.com/v1/videos/cgt-2025**** \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SOCIARO_API_KEY"

Full (Seedance 2.0 multimodal reference: image + image + video + audio, audio-video)

Create:

curl https://api.sociaro.com/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SOCIARO_API_KEY" \
  -d '{
    "model": "bytedance/dreamina-seedance-2-0",
    "content": [
      { "type": "text", "text": "Use the first-person POV framing from [Video 1] throughout, use [Audio 1] as background music; opening frame is [Image 1] ... the final frame freezes on Image 2. All background voice audio uses a female voice." },
      { "type": "image_url", "image_url": { "url": "https://.../r2v_tea_pic1.jpg" }, "role": "reference_image" },
      { "type": "image_url", "image_url": { "url": "https://.../r2v_tea_pic2.jpg" }, "role": "reference_image" },
      { "type": "video_url", "video_url": { "url": "https://.../r2v_tea_video1.mp4" }, "role": "reference_video" },
      { "type": "audio_url", "audio_url": { "url": "https://.../r2v_tea_audio1.mp3" }, "role": "reference_audio" }
    ],
    "generate_audio": true,
    "ratio": "16:9",
    "duration": 11,
    "watermark": false
  }'

→ { "id": "cgt-2026******-****" }

Full i2v (first + last frame) body (illustrating all optional top-level params)

{
  "model": "bytedance/seedance-1-0-pro",
  "content": [
    { "type": "text", "text": "..." },
    { "type": "image_url", "image_url": { "url": "data:image/png;base64,{...}" }, "role": "first_frame" },
    { "type": "image_url", "image_url": { "url": "https://.../last.png" }, "role": "last_frame" }
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5,
  "seed": 11,
  "camera_fixed": false,
  "watermark": true,
  "return_last_frame": true,
  "service_tier": "default",
  "execution_expires_after": 172800,
  "callback_url": "https://example.com/cb"
}

Draft mode (Seedance 1.5 Pro) — two-step

Step 1 (create draft):

{ "model": "bytedance/seedance-1-5-pro",
  "content": [ { "type": "text", "text": "..." } ],
  "draft": true }            // → returns draft task ID; generated at 480p

Step 2 (final video from draft):

{ "model": "bytedance/seedance-1-5-pro",
  "content": [ { "type": "draft_task", "draft_task": { "id": "<draft-task-id>" } } ],
  "resolution": "720p" }     // reuses draft's model/text/image_url/generate_audio/seed/ratio/duration/camera_fixed

Retrieve success response

{
  "id": "cgt-2025******-****",
  "model": "bytedance/dreamina-seedance-2-0",
  "status": "succeeded",
  "content": { "video_url": "https://.../****" },
  "usage": { "completion_tokens": 108900, "total_tokens": 108900 },
  "created_at": 1743414619,
  "updated_at": 1743414673,
  "seed": 10,
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "framespersecond": 24,
  "service_tier": "default",
  "execution_expires_after": 172800,
  "generate_audio": true,
  "draft": false,
  "priority": 0
}

Seedance 1.5 Pro

How to call

Through the Sociaro SDK / OpenAI-compatible door

Parameters — full schema

Coverage map (which model is covered by which API behaviour)

Critical per-model differences (capability matrix)

Endpoints (standard async video door)

CREATE — POST /v1/videos

Request body shape

CREATE — all top-level body parameters

CREATE — content[] item types

A) Text

B) Image (image_url)

C) Video (video_url) — new; Seedance 2.0 series only

D) Audio (audio_url) — new; Seedance 2.0 series only

E) Sample / Draft task (draft_task) — Seedance 1.5 Pro only

Pixel dimensions by resolution × ratio

CREATE — response

RETRIEVE — GET /v1/videos/{id}

Path parameter

Response shape

RETRIEVE — response parameters

LIST — GET /v1/videos (native Ark API only — not a gateway door)

LIST — request parameters (all are query-string parameters)

LIST — response shape

LIST — response parameters

CANCEL / DELETE — DELETE /v1/videos/{id} (native Ark API only — not a gateway door)

Path parameter

Behaviour by task status

Response

Examples

Minimal (text-to-video)

Full (Seedance 2.0 multimodal reference: image + image + video + audio, audio-video)

Full i2v (first + last frame) body (illustrating all optional top-level params)

Draft mode (Seedance 1.5 Pro) — two-step

Retrieve success response

CREATE — `POST /v1/videos`

CREATE — `content[]` item types

B) Image (`image_url`)

C) Video (`video_url`) — new; Seedance 2.0 series only

D) Audio (`audio_url`) — new; Seedance 2.0 series only

E) Sample / Draft task (`draft_task`) — Seedance 1.5 Pro only

RETRIEVE — `GET /v1/videos/{id}`

LIST — `GET /v1/videos` (native Ark API only — not a gateway door)

CANCEL / DELETE — `DELETE /v1/videos/{id}` (native Ark API only — not a gateway door)