Skip to main content
POST

Input Methods

Image URLs must be publicly accessible over HTTP(S). JPEG and PNG are supported, with a maximum of 10 MiB per image. You can add Suno reference audio to any generation method. After providing song_id, use song_window.start_s and song_window.end_s to specify a reference window whose length must equal duration. If no window is provided, the required duration is taken from the beginning of the song. lip_sync: true requires song_id.

Authorizations

TT-API-KEY
string
header
required

You can obtain your API key from the TTAPI Dashboard.

Body

application/json
prompt
string
required

Describe the scene, camera movement, and style.

Required string length: 1 - 30000
duration
integer
required

Generation duration in seconds.

Required range: 5 <= x <= 15
resolution
enum<string> | null
default:480p

Output resolution. 480p corresponds to fast; 720p corresponds to standard.

Available options:
480p,
720p
aspect_ratio
enum<string> | null
default:9:16

Video aspect ratio.

Available options:
1:1,
9:16,
16:9,
4:3,
3:4
first_frame_url
string<uri>

Public HTTP(S) URL of the first-frame image. Can be used alone, with a last frame, or with reference images.

last_frame_url
string<uri>

Public HTTP(S) URL of the last-frame image. Requires a first frame; the first-and-last-frame combination does not support reference images.

reference_image_urls
string<uri>[]

Up to 9 images. Can be used alone or with a first frame.

Maximum array length: 9

Public HTTP(S) URL of a reference image.

song_id
string

Suno song ID for reference audio. Can be combined with image inputs.

song_window
object

Reference audio window. Requires song_id. If omitted, uses a segment starting at second 0 with the same duration as the video.

lip_sync
boolean
default:false

Enable lip sync. Requires song_id when set to true.

hookUrl
string<uri>

Optional webhook callback URL. Sent via HTTP POST when the job finishes; the body matches the video job Fetch V2 response.

Response

Job accepted. Use data.jobId to query the result.

status
enum<string>
required
Available options:
SUCCESS
message
string
required

Job acceptance message.

data
object
required
Last modified on November 20, 2026