Image to Video

Image to Video API

The Image to Video API turns static images into playable videos. The endpoint combines the input image with the action, camera, atmosphere, and style descriptions in prompt, letting people, products, scenes, or character assets produce natural motion, camera push-ins, rotating showcases, or transition changes. When using bach-1.0, you can provide reference frames via image_url (first frame), end_image_url (last frame), or a combination of both, to control the video's opening frame, closing frame, or overall transition effect.

For the task status enum definitions, see API General Guide. To use local images, first obtain publicly accessible image URLs via Batch Uploads.

Create Task

Endpoint Information

  • Protocol: HTTPS
  • Endpoint: /videos/image2video
  • Method: POST
  • Request Format: application/json
  • Response Format: application/json

The full request URL is formed by concatenating the base URL and the endpoint path; see API General Guide.

Request Headers

Content-Type

Type: string ｜ Required: Yes ｜ Default: None

Data exchange format.

  • Fixed value: application/json

Authorization

Type: string ｜ Required: Yes ｜ Default: None

Authentication information, Bearer Token scheme.

  • Format: Bearer <API_TOKEN>
  • 【Note】There is exactly one space between Bearer and <API_TOKEN>.

Request Body

model_name

Type: string ｜ Required: No ｜ Default: bach-1.0

Model name. Enum values: bach-1.0.

image_url

Type: string ｜ Required: Optional ｜ Default: None

First-frame image URL, the starting reference frame of the generated video.

  • Must be a publicly accessible HTTP/HTTPS address.
  • 【Note】If end_image_url is not provided, image_url must be provided.

end_image_url

Type: string ｜ Required: Optional ｜ Default: None

Last-frame image URL, the closing target frame of the generated video.

  • Must be a publicly accessible HTTP/HTTPS address.
  • 【Note】If image_url is not provided, end_image_url must be provided; when both are provided, the video generates a natural transition between the first and last frames.

prompt

Type: string ｜ Required: No ｜ Default: None

Positive text prompt, i.e., the video content description.

  • Must not exceed 10,000 Chinese/English characters.
  • We recommend describing the subject's actions, camera changes, and target style for the image; the clearer the description, the more stable the generated result.

resolution

Type: string ｜ Required: Yes ｜ Default: None

Resolution of the generated video. Enum values: 720p, 1080p.

duration

Type: int ｜ Required: No ｜ Default: 6

Duration of the generated video, in seconds (s).

  • With last frame only, or first and last frames: 1~6s supported
  • With first frame only: 1~8s supported

generate_audio

Type: bool ｜ Required: No ｜ Default: false

Whether to generate audio along with the video. When true: synchronized audio generation is enabled When false: synchronized audio generation is disabled

audio_prompt

Type: string ｜ Required: No ｜ Default: None

Audio or sound-effect description, which can be used to add sound effects or narration information.

  • Must not exceed 200 Chinese/English characters.

enable_moderation

Type: bool ｜ Required: No ｜ Default: true

Whether to enable content moderation. When true: content moderation is enabled When false: content moderation is disabled

  • 【Note】enable_moderation only takes effect after being configured by an administrator. Please contact your administrator if needed.

callback_url

Type: string ｜ Required: No ｜ Default: Empty

Callback notification URL for this task's result

  • Must be a valid HTTP/HTTPS URL
  • Must not exceed 500 characters.
  • If configured, the server will proactively send notifications when the task status changes; for the notification message schema, see Using Callbacks.

Request Examples

First frame only (image_url)

When image_url is provided, the endpoint generates a video based on this product, portrait, or scene image, giving the static frame natural motion, camera changes, or showcase effects.

bash
Copy
curl --location --request POST '<BASE_URL>/videos/image2video' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "model_name": "bach-1.0",
    "image_url": "https://example.com/images/product-scene.jpg",
    "prompt": "Camera slowly pushes in, the product rotates gently under soft light, the background stays clean and premium",
    "resolution": "1080p",
    "duration": 6,
    "generate_audio": false
}'

Last frame only (end_image_url)

When only end_image_url is provided, the video converges toward that target last frame, suitable for scenarios where you want to control the final composition, product placement, or brand frame.

bash
Copy
curl --location --request POST '<BASE_URL>/videos/image2video' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "model_name": "bach-1.0",
    "end_image_url": "https://example.com/images/final-frame.jpg",
    "prompt": "Camera pushes in naturally from a clean light-colored background, the product gradually enters the frame, finally settling into the last-frame composition",
    "resolution": "1080p",
    "duration": 6,
    "generate_audio": false
}'

First and last frames (image_url + end_image_url)

When both image_url and end_image_url are provided, the video generates a natural transition between the first and last frames, suitable for product showcases, character actions, or camera-convergence scenarios that need an explicit opening frame and closing frame.

bash
Copy
curl --location --request POST '<BASE_URL>/videos/image2video' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "model_name": "bach-1.0",
    "image_url": "https://example.com/images/start-frame.jpg",
    "end_image_url": "https://example.com/images/end-frame.jpg",
    "prompt": "Camera pushes forward smoothly from the first frame, the product rotates slightly to show material details, finally transitioning naturally to the last frame",
    "resolution": "1080p",
    "duration": 6,
    "generate_audio": false
}'

Response Body

json
Copy
{
    "code": 200,                                          // Status code; see "Error Handling" for definitions
    "data": {
        "task_id": "550e8400-e29b-41d4-a716-446655440000", // Task ID, generated by the system, used to query the task result later
        "status": "TASK_PENDING",                          // Task status; for enum values see "API General Guide - Task Status"
        "created_at": 1778313600                           // Task creation time, Unix timestamp, unit: seconds (s)
    },
    "timestamp": 1778313600                                // Response time, Unix timestamp, unit: seconds (s)
}

task_id

Type: string

Task ID, generated by the system.

  • 【Note】Please store it safely; it is used to query the task result.

status

Type: string

Task status; for enum values see API General Guide.

created_at

Type: number

Task creation time, Unix timestamp, unit: seconds (s).

Query Task (Single)

Endpoint Information

  • Protocol: HTTPS
  • Endpoint: /videos/image2video/{task_id}
  • Method: GET
  • Request Format: application/json
  • Response Format: application/json

Request Headers

Content-Type

Type: string ｜ Required: Yes ｜ Default: None

Data exchange format.

  • Fixed value: application/json

Authorization

Type: string ｜ Required: Yes ｜ Default: None

Authentication information, Bearer Token scheme.

  • Format: Bearer <API_TOKEN>
  • 【Note】There is exactly one space between Bearer and <API_TOKEN>.

Path Parameters

task_id

Type: string ｜ Required: Yes ｜ Default: None

The Image to Video task ID.

  • 【Note】This is a path parameter; fill the value directly into the request path. Its value is the task_id returned by the create-task endpoint.

Request Example

bash
Copy
curl --location --request GET '<BASE_URL>/videos/image2video/550e8400-e29b-41d4-a716-446655440000' \
--header 'Authorization: Bearer <API_TOKEN>'

Response Body

json
Copy
{
    "code": 200,                                           // Status code; see "Error Handling" for definitions
    "data": {
        "task_id": "550e8400-e29b-41d4-a716-446655440000",  // Task ID, generated by the system
        "status": "TASK_SUCCEEDED",                         // Task status; for enum values see "API General Guide - Task Status"
        "created_at": 1778313600,                           // Task creation time, Unix timestamp, unit: seconds (s)
        "started_at": 1778313610,                           // Task processing start time, Unix timestamp, unit: seconds (s)
        "completed_at": 1778313700,                         // Task completion time, Unix timestamp, unit: seconds (s)
        "video_url": "https://example.com/result.mp4"       // Resource URL of the generated video
    },
    "timestamp": 1778313700                                 // Response time, Unix timestamp, unit: seconds (s)
}

task_id

Type: string

Task ID, generated by the system.

status

Type: string

Task status; for enum values see API General Guide.

created_at

Type: number

Task creation time, Unix timestamp, unit: seconds (s).

started_at

Type: number

Task processing start time, Unix timestamp, unit: seconds (s).

completed_at

Type: number

Task completion time, Unix timestamp, unit: seconds (s).

video_url

Type: string

Resource URL of the generated video.

  • 【Note】For data security, we recommend transferring and storing the generated video promptly.
Previous
Text to Video
Next
Montage
On this page
Image to Video | bach.art | bach.art