Text to Video

Text to Video API

The Text to Video API generates videos directly from text prompts. In prompt, you can describe the visual subject, actions, scene atmosphere, camera movement, and visual style, and use parameters such as duration, resolution, and aspect_ratio to control the output video's length, clarity, and frame aspect ratio.

For the task status enum definitions, see API General Guide.

Create Task

Endpoint Information

  • Protocol: HTTPS
  • Endpoint: /videos/text2video
  • 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.

prompt

Type: string ｜ Required: Yes ｜ Default: None

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

  • Must not exceed 10,000 Chinese/English characters.
  • We recommend including five kinds of information — subject, action, scene, camera, and style; the clearer the description, the more stable the generated result.

negative_prompt

Type: string ｜ Required: No ｜ Default: None

Negative text prompt, i.e., content you do not want to appear in the video.

  • Must not exceed 10,000 Chinese/English characters.

resolution

Type: string ｜ Required: Yes ｜ Default: None

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

aspect_ratio

Type: string ｜ Required: No ｜ Default: 16:9

Frame aspect ratio (width:height) of the generated video. Enum values: 16:9, 9:16, 1:1.

duration

Type: int ｜ Required: No ｜ Default: 8

Duration of the generated video, in seconds (s).
Value range: 1 ~ 8.

cfg_scale

Type: float ｜ Required: No ｜ Default: 5.0

Prompt guidance strength, i.e., how closely the generated video follows the prompt.

  • Value range: 1.0 ~ 15.0.
  • The larger the value, the stronger the correlation between the video and the prompt.

enhance_prompt

Type: bool ｜ Required: No ｜ Default: true

Whether to enable prompt enhancement. When true: prompt enhancement is enabled When false: prompt enhancement is disabled

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 content description.

  • Must not exceed 200 Chinese/English characters.
  • 【Note】Only takes effect when generate_audio is true.

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 Example

bash
Copy
curl --location --request POST '<BASE_URL>/videos/text2video' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "model_name": "<MODEL_NAME>",
    "prompt": "Sunset over the sea, golden light spilling across the water, camera slowly pushing forward, cinematic look",
    "negative_prompt": "blurry, low quality, distorted frame",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8,
    "cfg_scale": 5.0,
    "generate_audio": false,
    "enable_moderation": true
}'

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/text2video/{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 Text 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/text2video/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
Error Codes
Next
Image to Video
On this page
Text to Video | bach.art | bach.art