Skip to main content
POST
/
sora
/
generations
cURL
curl --request POST \
  --url https://api.ttapi.io/sora/generations \
  --header 'Content-Type: application/json' \
  --header 'TT-API-KEY: <api-key>' \
  --data '
{
  "model": "sora-2",
  "prompt": "<string>",
  "referImages": [
    "https://cdn.ttapi.io/demo/2025-03-30/5d17dd5207daeeac86bcecd2d6405a0.jpg"
  ],
  "orientation": "portrait",
  "duration": 123,
  "size": "small",
  "character_url": "<string>",
  "character_timestamps": "1,3",
  "private": "true",
  "hookUrl": "<string>"
}
'
{
  "status": "SUCCESS",
  "message": "success",
  "data": {
    "job_id": "job_id"
  }
}

Authorizations

​
TT-API-KEY
string
header
required

You can obtain your API key from the TTAPI Dashboard.

Body

application/json

Note: The synchronous response from the Sora video generation interface is not the final result of the task. The final result needs to be received via asynchronous notification using the hookUrl parameter, or by querying through the Sora fetch task result interface.

​
model
enum<string>
required

sora-2 normal mode sora-2-pro HD mode

Available options:
sora-2,
sora-2-pro
Example:

"sora-2"

​
prompt
string
required

Video description

​
referImages
array

Reference image array, cannot pass real images with avatars or any existing US product logos. As per OpenAI regulations, non-compliant images will cause task failure. Currently only the first URL is used

Example:
[
  "https://cdn.ttapi.io/demo/2025-03-30/5d17dd5207daeeac86bcecd2d6405a0.jpg"
]
​
orientation
enum<string>

Video orientation. In sora-2 mode, portrait video resolution is approximately 720 * 1280, landscape is similar ratio. In sora-2-pro mode, portrait video resolution is approximately 1024 * 1792, landscape is similar ratio

Available options:
portrait,
landscape
​
duration
integer

Video duration in seconds. 25s only works in sora-2-pro model
Supported values: 10, 15, 25
Default is 10s for sora-2 model, 15s for sora-2-pro model

​
size
enum<string>
default:small

Video quality setting. Only supported in sora-2-pro mode. For 25s duration, only standard quality is available

Available options:
small,
large
​
character_url
string

Video URL for character creation
Important: The video must not contain any real people, otherwise the task will fail

​
character_timestamps
string

Time range in seconds for character appearance in video, format: {start},{end}. Note: The range of end-start must be between 1 to 3 seconds

Example:

"1,3"

​
private
boolean
default:true

Privacy setting for generated video. true - Private access, false - Public access

​
hookUrl
string

Callback notification URL. When task completes or fails, this URL will be notified. Notification data structure is consistent with fetch structure. If not set, you need to request the fetch interface for query

Response

Request successful

​
status
string
required
Example:

"SUCCESS"

​
message
string
required
Example:

"success"

​
data
object
required
Example:
{ "job_id": "job_id" }
Last modified on March 13, 2026