> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ttapi.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Sora API Documentation - Generate Video
> Generate videos from text & images
Start here if you need the main endpoint for **Sora 2 API** video generation.
For the complete endpoint directory, workflow guidance, and related links, see the [Sora 2 API overview](/api/en/sora).
## OpenAPI
````yaml openapi/en/sora.json POST /sora/generations
openapi: 3.1.0
info:
title: Sora API DOCS
version: 1.0.0
description: TTAPI Sora API service
servers:
- url: https://api.ttapi.io
security: []
paths:
/sora/generations:
post:
description: Generate videos from text & images
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GenerationsRequest'
responses:
'200':
$ref: '#/components/responses/SuccessResponse'
'400':
$ref: '#/components/responses/400Response'
'401':
$ref: '#/components/responses/401Response'
security:
- CustomApiKey: []
components:
schemas:
GenerationsRequest:
type: object
description: >-
**Note**: The synchronous response from the Sora video generation
endpoint 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 endpoint.
properties:
model:
type: string
example: sora-2
description: sora-2 normal mode sora-2-pro HD mode
enum:
- sora-2
- sora-2-pro
prompt:
type: string
description: Video description
referImages:
type: array
items:
type: string
enum:
- >-
https://cdn.ttapi.io/demo/2025-03-30/5d17dd5207daeeac86bcecd2d6405a0.jpg
description: >-
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**
orientation:
type: string
description: >-
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
enum:
- portrait
- landscape
duration:
type: integer
description: >-
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:
type: string
description: >-
Video quality setting. Only supported in sora-2-pro mode. For 25s
duration, only standard quality is available
enum:
- small
- large
default: small
character_url:
type: string
description: >-
Video URL for character creation
**Important: The video must
not contain any real people, otherwise the task will fail**
character_timestamps:
type: string
example: 1,3
description: >-
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
private:
type: boolean
default: 'true'
description: >-
Privacy setting for generated video. true - Private access, false -
Public access
hookUrl:
type: string
description: >-
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
endpoint for query
required:
- prompt
- model
responses:
SuccessResponse:
description: Request successful
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: SUCCESS
message:
type: string
example: success
data:
type: object
example:
jobId: jobId
required:
- status
- message
- data
400Response:
description: Parameter error
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: FAILED
message:
type: string
example: '"prompt" cannot be empty.'
data:
type: object
required:
- status
- message
401Response:
description: Authorization failed
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: FAILED
message:
type: string
example: Wrong TT-API-KEY or email is not activated.
required:
- status
- message
securitySchemes:
CustomApiKey:
type: apiKey
in: header
name: TT-API-KEY
description: >-
You can obtain your API key from the TTAPI Dashboard.
````