Image to Video API

Description

The Image to Video API turns a single static image into a dynamic video. Provide the subject or scene image via image_url, then use prompt to describe the motion, camera work, atmosphere, and style, so the frame moves naturally while preserving the original visual characteristics. This endpoint is ideal for rapidly expanding product photos, portraits, scene concept art, or visual drafts into short-form video assets.

Use Cases

• Turn existing images, posters, or product photos into playable video content.
• Bring natural motion and camera changes to characters, products, scenes, or character assets.
• Produce social media clips, ad drafts, and creative previews based on an established visual direction.

Endpoint Information

The full request URL consists of the base URL and the endpoint path; see API Basics.

Create Task

Request Parameters

Constraints: image_url and resolution are required; image_url must be an accessible HTTP/HTTPS URL; resolution only supports 720p and 1080p; duration supports 1-6 seconds; fps only supports 24 and 30.

Request Example

curl -X POST '<BASE_URL>/videos/image2video' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -d '{
    "model_name": "bach-1.0-preview",
    "image_url": "https://example.com/images/product-scene.jpg",
    "prompt": "Camera slowly pushes in, the product rotates gently under soft lighting, background stays clean and premium",
    "negative_prompt": "blurry, low quality, distorted frames",
    "resolution": "1080p",
    "duration": 6,
    "fps": 24,
    "generate_audio": false
  }'

Success Response

{
  "code": 200,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": 1778313600,
    "status": "TASK_PENDING"
  },
  "timestamp": 1778313600
}

Query Task

Path Parameters

Request Example

curl -X GET '<BASE_URL>/videos/image2video/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer <API_TOKEN>'

Success Response

{
  "code": 200,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "TASK_SUCCEEDED",
    "created_at": 1778313600,
    "started_at": 1778313610,
    "completed_at": 1778313700,
    "video_url": "https://example.com/result.mp4"
  },
  "timestamp": 1778313700
}

Notes

• Image to Video requires one image URL. We recommend using Batch Upload first to obtain a stable, accessible image URL.
• We recommend that prompt describe the subject's motion, camera changes, and target style; the clearer the description, the more stable the results.
• Image to Video generates at a fixed aspect ratio; if you want to generate visuals directly from text, use the Text to Video API.
• If you need a task completion notification, pass a callback_url — see Using Callbacks for the callback protocol; otherwise, retrieve the task status via the query endpoint.

Related Documents

• API Basics
• Capability Map
• Batch Upload
• Using Callbacks
• Error Handling