Seedance 2.x Video API Documentation

Overview

Build Seedance 2.x Video integrations with HeadSwap. Review authentication, request parameters, task creation, status, and result endpoints.

Primary Endpoint

POST/api/v1/seedance2Video/start

Generate videos with Seedance 2.0 (standard/mini/fast) or Seedance 2.5 (model_version=2.5). Supports text-to-video, image-to-video, first-last-frames, and reference modes. Image / video / audio inputs must be public URLs (asset:// URIs are not accepted from clients). Seedance 2.5 raises the limits: single-shot output up to 30s (2.0: 15s), up to 30 reference images / 10 reference videos / 10 reference audios (2.0: 9 / 3 / 3), reference video total duration up to 30s, resolution up to 1080p, and audio-only references are allowed (2.0 requires at least one image or video). ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/seedance2Video/allRecords` — Get all records. - `GET /api/v1/seedance2Video/{_id}` — Get task detail. - `PUT /api/v1/seedance2Video/{_id}` — Rename task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).

Request Parameters

Name	Type	Required	Description
name	string	No	-
mode	enum: text-to-video \| image-to-video \| first-last-frames \| reference	No	image-to-video uses image_url (+ optional last_frame_url); first-last-frames uses first_frame_url + last_frame_url; reference accepts any combination of reference_urls (image) / video_urls / audio_urls. On Seedance 2.0 audio cannot be used alone and must accompany at least one image or video reference; on Seedance 2.5 audio-only references are supported.; default: "text-to-video"
model_version	enum: standard \| mini \| fast \| 2.5	No	standard / mini / fast select a Seedance 2.0 tier. "2.5" selects Seedance 2.5, which currently has a single tier and higher input limits (see duration / reference_urls / video_urls / audio_urls).; default: "standard"
omni_reference_task_type	enum: reference \| edit \| extend	No	Seedance 2.5 reference-mode task hint. edit uses ratio=adaptive and duration=-1; extend uses ratio=adaptive; reference keeps the requested ratio and duration. edit currently accepts exactly one video_url. auto is intentionally not exposed because its output duration is unknown before billing.
prompt	string	Yes	-
image_url	string	No	First frame for image-to-video mode.
first_frame_url	string	No	Required for first-last-frames mode.
last_frame_url	string	No	Optional last frame for image-to-video; required for first-last-frames.
reference_urls	array<string>	No	Reference images for reference mode. Max 9 on Seedance 2.0, max 30 on Seedance 2.5.; maxItems: 30
video_urls	array<string>	No	Reference videos (mp4/mov). Seedance 2.0: max 3 clips, each 2-15s, total <= 15 × number_of_videos seconds. Seedance 2.5: max 10 clips with a combined cap of 30s; omni_reference_task_type=edit currently requires exactly one clip. The server always probes video_urls (public hosts only, with separate connection/download/parse limits) as the authoritative duration for billing.; maxItems: 10
audio_urls	array<string>	No	Reference audios (mp3/wav). Seedance 2.0: max 3 clips, each 2-15s, total <=15s, and audio cannot be used standalone (at least one image or video reference is required). Seedance 2.5: max 10 clips and audio-only references are allowed.; maxItems: 10
input_video_duration	number	No	Optional client estimate of the total reference-video duration in seconds. This value is never trusted for final billing: the server always probes video_urls and bills on max(measured, this value), so passing a smaller number does not lower the price. Must be within [2, 15 × number_of_videos] on Seedance 2.0 and within [2, 30] on Seedance 2.5.; minimum: 2; maximum: 45.5
duration	integer	No	Output length in seconds. Max 15 on Seedance 2.0; max 30 on Seedance 2.5. Seedance 2.5 edit tasks require -1.; default: 5
aspect_ratio	enum: adaptive \| 21:9 \| 16:9 \| 4:3 \| 1:1 \| 3:4 \| 9:16	No	default: "16:9"
resolution	enum: 480p \| 720p \| 1080p \| 4k	No	Only the standard tier of Seedance 2.0 supports 4k. Seedance 2.5 supports 480p / 720p / 1080p. The fast / mini tiers of Seedance 2.0 are limited to 480p / 720p.; default: "720p"
generate_audio	boolean	No	Defaults to true to match billing (audio is included); pass false explicitly to disable.; default: true
minor_suspected_skip	boolean	No	Skip soft minor-suspect block (code 1004); hard CSAM block (code 1003) is always enforced.; default: false
webhook_url	string	No	HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.; maxLength: 2048
webhook_token	string	No	Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.; maxLength: 256

Request schema and conditional rules

{
  "allOf": [
    {
      "type": "object",
      "required": [
        "prompt"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "mode": {
          "type": "string",
          "enum": [
            "text-to-video",
            "image-to-video",
            "first-last-frames",
            "reference"
          ],
          "default": "text-to-video",
          "description": "image-to-video uses image_url (+ optional last_frame_url); first-last-frames uses first_frame_url + last_frame_url; reference accepts any combination of reference_urls (image) / video_urls / audio_urls. On Seedance 2.0 audio cannot be used alone and must accompany at least one image or video reference; on Seedance 2.5 audio-only references are supported."
        },
        "model_version": {
          "type": "string",
          "enum": [
            "standard",
            "mini",
            "fast",
            "2.5"
          ],
          "default": "standard",
          "description": "standard / mini / fast select a Seedance 2.0 tier. \"2.5\" selects Seedance 2.5, which currently has a single tier and higher input limits (see duration / reference_urls / video_urls / audio_urls)."
        },
        "omni_reference_task_type": {
          "type": "string",
          "enum": [
            "reference",
            "edit",
            "extend"
          ],
          "description": "Seedance 2.5 reference-mode task hint. edit uses ratio=adaptive and duration=-1; extend uses ratio=adaptive; reference keeps the requested ratio and duration. edit currently accepts exactly one video_url. auto is intentionally not exposed because its output duration is unknown before billing."
        },
        "prompt": {
          "type": "string"
        },
        "image_url": {
          "type": "string",
          "description": "First frame for image-to-video mode."
        },
        "first_frame_url": {
          "type": "string",
          "description": "Required for first-last-frames mode."
        },
        "last_frame_url": {
          "type": "string",
          "description": "Optional last frame for image-to-video; required for first-last-frames."
        },
        "reference_urls": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 30,
          "description": "Reference images for reference mode. Max 9 on Seedance 2.0, max 30 on Seedance 2.5."
        },
        "video_urls": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 10,
          "description": "Reference videos (mp4/mov). Seedance 2.0: max 3 clips, each 2-15s, total <= 15 × number_of_videos seconds. Seedance 2.5: max 10 clips with a combined cap of 30s; omni_reference_task_type=edit currently requires exactly one clip. The server always probes video_urls (public hosts only, with separate connection/download/parse limits) as the authoritative duration for billing."
        },
        "audio_urls": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 10,
          "description": "Reference audios (mp3/wav). Seedance 2.0: max 3 clips, each 2-15s, total <=15s, and audio cannot be used standalone (at least one image or video reference is required). Seedance 2.5: max 10 clips and audio-only references are allowed."
        },
        "input_video_duration": {
          "type": "number",
          "minimum": 2,
          "maximum": 45.5,
          "description": "Optional client estimate of the total reference-video duration in seconds. This value is never trusted for final billing: the server always probes video_urls and bills on max(measured, this value), so passing a smaller number does not lower the price. Must be within [2, 15 × number_of_videos] on Seedance 2.0 and within [2, 30] on Seedance 2.5."
        },
        "duration": {
          "type": "integer",
          "oneOf": [
            {
              "enum": [
                -1
              ]
            },
            {
              "minimum": 4,
              "maximum": 30
            }
          ],
          "default": 5,
          "description": "Output length in seconds. Max 15 on Seedance 2.0; max 30 on Seedance 2.5. Seedance 2.5 edit tasks require -1."
        },
        "aspect_ratio": {
          "type": "string",
          "enum": [
            "adaptive",
            "21:9",
            "16:9",
            "4:3",
            "1:1",
            "3:4",
            "9:16"
          ],
          "default": "16:9"
        },
        "resolution": {
          "type": "string",
          "enum": [
            "480p",
            "720p",
            "1080p",
            "4k"
          ],
          "default": "720p",
          "description": "Only the standard tier of Seedance 2.0 supports 4k. Seedance 2.5 supports 480p / 720p / 1080p. The fast / mini tiers of Seedance 2.0 are limited to 480p / 720p."
        },
        "generate_audio": {
          "type": "boolean",
          "default": true,
          "description": "Defaults to true to match billing (audio is included); pass false explicitly to disable."
        },
        "minor_suspected_skip": {
          "type": "boolean",
          "default": false,
          "description": "Skip soft minor-suspect block (code 1004); hard CSAM block (code 1003) is always enforced."
        }
      }
    },
    {
      "$ref": "#/components/schemas/WebhookInput"
    }
  ]
}

Response Fields

code: enum: 0
data: object
data._id: string: Task ID for detail and batch polling.
data.name: string
data.prompt: string
data.is_downloaded: boolean
data.is_previewed: boolean
data.current_status: string: Persisted task state; use the concrete task family schema for its allowed values and terminal states.
data.createdAt: string
data.updatedAt: string
data.expirationDate: string
data.remainingDays: number
data.isExpired: boolean
data.coins: number
data.hasRefundCoin: boolean: Whether charged credits were refunded.
data.failed_code: string
data.failed_message: string
data.failed_reason: string: Public failure category when available.
data.image_url: string
data.image_urls: array<string>
data.result_url: string
data.video_url: string
data.result_video_url: string
data.cover_url: string
data.result_cover: string
data.hd_video_url: string
data.video_time: number
data.duration_seconds: number
trace_id: string: Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.

Request Example

curl -X POST "https://headswap.app/api/v1/seedance2Video/start" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "high quality, clear, cinematic"
}'

Related Endpoints

GET/api/v1/seedance2Video/{_id}

Get task detail

POST/api/v1/seedance2Video/start

Start Seedance 2.x video generation

GET/api/v1/seedance2Video/allRecords

Get all records

POST/api/v1/seedance2Video/batchDetail

Batch get task details

PUT/api/v1/seedance2Video/{_id}

Rename task

DELETE/api/v1/seedance2Video/{_id}

Delete task

Responses

200

Task started successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.

401

Unauthorized - Invalid or missing bearer token