Seedance 1.5 Video API Documentation

Overview

Build Seedance 1.5 Video integrations with A2E. Review authentication, request parameters, task creation, status, and result endpoints.

Primary Endpoint

POST/api/v1/seedanceVideo/start

Generate videos using BytePlus ModelArk Seedance 1.5 Pro. Supports 3 modes - text-to-video, image-to-video, first-last-frames. ### 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 - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/seedanceVideo/allRecords` — Get all Seedance video records. - `GET /api/v1/seedanceVideo/{_id}` — Get Seedance video detail. - `PUT /api/v1/seedanceVideo/{_id}` — Update Seedance video name. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).

Request Parameters

Name	Type	Required	Description
name	string	No	Name of the video generation task
mode	enum: text-to-video \| image-to-video	No	Generation mode. For first-last-frames usage, send mode=image-to-video together with image_url + end_image_url; the backend will normalize it.; default: "text-to-video"
prompt	string	Yes	Text prompt describing the desired video
image_url	string	No	Input image URL (required for image-to-video mode; also used as the first frame in first-last-frames usage)
end_image_url	string	No	Last frame image URL. When provided together with image_url, mode is automatically treated as first-last-frames.
duration	enum: 5 \| 10	No	Video duration in seconds; default: "5"
aspect_ratio	enum: 16:9 \| 9:16 \| 1:1	No	Video aspect ratio; default: "16:9"
resolution	enum: 480p \| 720p	No	Video resolution; default: "720p"
camera_fixed	boolean	No	Whether the camera is fixed; default: false
generate_audio	boolean	No	Whether to generate audio; default: false
minor_suspected_skip	boolean	No	Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block.; 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",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the video generation task",
          "example": "My Seedance Video"
        },
        "mode": {
          "type": "string",
          "enum": [
            "text-to-video",
            "image-to-video"
          ],
          "description": "Generation mode. For first-last-frames usage, send mode=image-to-video together with image_url + end_image_url; the backend will normalize it.",
          "default": "text-to-video",
          "example": "image-to-video"
        },
        "prompt": {
          "type": "string",
          "description": "Text prompt describing the desired video",
          "example": "A girl holding a fox, the girl opens her eyes..."
        },
        "image_url": {
          "type": "string",
          "description": "Input image URL (required for image-to-video mode; also used as the first frame in first-last-frames usage)",
          "example": "https://example.com/input.jpg"
        },
        "end_image_url": {
          "type": "string",
          "description": "Last frame image URL. When provided together with image_url, mode is automatically treated as first-last-frames.",
          "example": "https://example.com/last.jpg"
        },
        "duration": {
          "type": "string",
          "enum": [
            "5",
            "10"
          ],
          "description": "Video duration in seconds",
          "default": "5"
        },
        "aspect_ratio": {
          "type": "string",
          "enum": [
            "16:9",
            "9:16",
            "1:1"
          ],
          "description": "Video aspect ratio",
          "default": "16:9"
        },
        "resolution": {
          "type": "string",
          "enum": [
            "480p",
            "720p"
          ],
          "description": "Video resolution",
          "default": "720p"
        },
        "camera_fixed": {
          "type": "boolean",
          "description": "Whether the camera is fixed",
          "default": false
        },
        "generate_audio": {
          "type": "boolean",
          "description": "Whether to generate audio",
          "default": false
        },
        "minor_suspected_skip": {
          "type": "boolean",
          "default": false,
          "description": "Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."
        }
      },
      "required": [
        "prompt"
      ]
    },
    {
      "$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://www.a2e.com.cn/api/v1/seedanceVideo/start" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "A girl holding a fox, the girl opens her eyes..."
}'

Related Endpoints

GET/api/v1/seedanceVideo/{_id}

Get Seedance video detail

POST/api/v1/seedanceVideo/start

Start Seedance 1.5 Pro video generation

GET/api/v1/seedanceVideo/allRecords

Get all Seedance video records

POST/api/v1/seedanceVideo/batchDetail

Batch get Seedance 1.5 task details

PUT/api/v1/seedanceVideo/{_id}

Update Seedance video name

DELETE/api/v1/seedanceVideo/{_id}

Delete Seedance video

Responses

200

Video generation 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.

400

Bad Request - Invalid parameters

401

Unauthorized - Invalid or missing bearer token