bytedance/seedance-2-5/image-to-video

1. Authentication

The API uses an API key for authentication.

Get Your API Key

Get your API key from https://icreat.ai/hub/keys.

2. Call the API

Submit a Request

Use cURL to submit an HTTP request and start an image-to-video generation task using reference images:

curl --fail-with-body --connect-timeout 10 --max-time 60 \
  -X POST https://api.icreat.ai/v1/task/submit/bytedance/seedance-2-5/image-to-video \
  -H "Authorization: Bearer ${ICREAT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "content": [
    {
      "type": "text",
      "text": "A cat is playing with a ball"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/reference.jpg"
      },
      "role": "reference_image"
    }
  ],
  "generate_audio": true,
  "ratio": "3:4",
  "duration": 5,
  "resolution": "480p"
}'

The server will return a response body similar to the following:

{ "task_id": "task-xxx" }

Use the task_id to poll the task status and retrieve the result.

3. Poll the Task Status

curl --connect-timeout 10 --max-time 60 \
  -X POST "https://api.icreat.ai/v1/task/query-status" \
  -H "Authorization: Bearer ${ICREAT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "task_id": "task-xxx"
}'

The server will return the task status. When the status is SUCCEEDED, you can retrieve the generated result.

4. Retrieve the Result

curl --connect-timeout 10 --max-time 60 \
  -X POST "https://api.icreat.ai/v1/task/get-result" \
  -H "Authorization: Bearer ${ICREAT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "task_id": "task-xxx"
}'

The server will return the video generated by the task.

5. Schema

Top-Level Fields

The API uses a multimodal input structure. content is a required array containing a text prompt and reference images.

Field	Type	Required	Description
`content`	object[]	Yes	Multimodal content array containing the text prompt and reference images.
`generate_audio`	boolean	No	Whether to generate audio.
`ratio`	string	No	Output video aspect ratio. Supported values: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, and `adaptive`. When set to `adaptive`, the model automatically selects a suitable aspect ratio based on the input.
`resolution`	string	No	Output video resolution. Supported values: `480p` and `720p`.
`duration`	integer	No	Video duration in seconds. Supports integers from `4` to `30`, or `-1` to let the model automatically select the duration.
`watermark`	boolean	No	Whether to add an “AI Generated” watermark.

`content[]` Items

Field	Type	Required	Description
`type`	string	Yes	Content type. Supported values: `text` and `image_url`.
`text`	string	Conditionally required	Required when `type` is `text`. Used to describe the video content. Supports Chinese, English, Japanese, Indonesian, Spanish, and Portuguese.
`image_url`	object	Conditionally required	Required when `type` is `image_url`. Format: `{"url":"https://..."}`.
`role`	string	Required for media	Role of the reference image. For reference image-to-video generation, it must be set to `reference_image`.
`need_review`	boolean	No	Whether to submit the reference image for official review. Set this to `true` when the reference image contains a face or copyrighted IP.

Chinese prompts must not exceed 2,000 characters, and English prompts must not exceed 2,000 words. Overly long prompts may dilute key information and cause the model to overlook certain details.

`need_review` Guidelines

If the reference image contains a face or copyrighted IP, set need_review to true; otherwise, generation may fail.
If a reference image requires review but need_review is set to false, the task may fail.
If a reference image does not require review but need_review is set to true, generation may take longer.

Reference Image Requirements

Supported formats: jpeg, png, webp, bmp, tiff, gif, heic, and heif
Aspect ratio (width/height): 0.4–2.5
Width and height: 300–6000 px
Maximum size per image: less than 30 MB
Maximum request body size: 64 MB
Supports 1–30 reference images
The role of each reference image must be set to reference_image

6. Input Examples

6.1 Image-to-Video with a Reference Image

{
  "content": [
    {
      "type": "text",
      "text": "A cat is playing with a ball"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/reference.jpg"
      },
      "role": "reference_image"
    }
  ],
  "generate_audio": true,
  "ratio": "3:4",
  "duration": 5,
  "resolution": "480p"
}

6.2 Image-to-Video with Multiple Reference Images

{
  "content": [
    {
      "type": "text",
      "text": "A cat is playing with a ball"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/cat.jpg"
      },
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/ball.jpg"
      },
      "role": "reference_image"
    }
  ],
  "generate_audio": true,
  "ratio": "3:4",
  "duration": 5,
  "resolution": "480p"
}

6.3 Reference Image Containing a Face or Copyrighted IP

{
  "content": [
    {
      "type": "text",
      "text": "A character walking through a futuristic city"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/reference.jpg"
      },
      "role": "reference_image",
      "need_review": true
    }
  ],
  "generate_audio": true,
  "ratio": "16:9",
  "duration": 5,
  "resolution": "720p"
}