Sora-2 interface document

Overview

Sora 2 is a video generation model launched by OpenAI, supporting Text-to-Video (T2V), Image-to-Video (I2V), and Video-to-Video (V2V, see Remix mode documentation) functions. This document describes how to invoke Sora 2 for video generation via the Nebula API.

Basic Information

Item	Content
Base URL	`https://llm.ai-nebula.com`
Authentication	API Key (Token)
Request Header	`Authorization: Bearer sk-xxxx`
Content-Type	`application/json`
Task Mode	Asynchronous Task (Submit Task → Poll Status → Download Result)

Supported Models

sora-2 - Sora 2 Standard Edition

API Endpoints

1. Submit Video Generation Task

Endpoint: POST /v1/video/generations

Request Headers:

Authorization: Bearer sk-xxxx
Content-Type: application/json

Request Parameters:

Parameter Name	Type	Required	Description	Example
`model`	string	Yes	Model name	`"sora-2"`
`prompt`	string	Yes	Video generation prompt	`"A cute kitten playing in the garden"`
`seconds`	string/int	No	Video duration (seconds), supports: 4, 8, 12; default: 4	`"4"` or `8`
`size`	string	No	Video resolution, supports: `"720x1280"` (portrait) or `"1280x720"` (landscape). Note: only images of the exact dimensions can be passed	`"720x1280"`
`width`	int	No	Video width (used with `height`, automatically converts to `size`)	`720`
`height`	int	No	Video height (used with `width`, automatically converts to `size`)	`1280`
`input_reference`	string	No	Reference image (supports URL or base64 format)	`"https://example.com/image.jpg"` or `"data:image/jpeg;base64,..."`
`remix_from_video_id`	string	No	Remix Mode: Regenerate based on an existing video ID (must start with `video_`)	`"video_12345"`
`user`	string	No	User identifier	`"user-1234"`

Request Example 1: Basic Text-to-Video

Request Example 2: Using Image Reference (I2V)

Request Example 3: Using Base64 Image

Request Example 4: Remix Mode

Response Example:

{
  "format": "mp4",
  "metadata": {
    "completed_at": null,
    "created_at": 1762220876,
    "error": null,
    "expires_at": null,
    "id": "video_69095b4ce0048190893a01510c0c98b0",
    "model": "sora-2",
    "object": "video",
    "progress": 0,
    "remixed_from_video_id": null,
    "seconds": "4",
    "size": "1280x720",
    "status": "queued"
  },
  "status": "submitted",
  "task_id": "video_69095b4ce0048190893a01510c0c98b0"
}

Response Field Description:

Field Name	Type	Description
`task_id`	string	Task ID, used for subsequent status queries and video downloading
`status`	string	Task status, initial value is `"submitted"`

2. Query Task Status

Endpoint: GET /v1/video/generations/{task_id}

Request Header:

Authorization: Bearer sk-xxxx

Path Parameters:

Parameter Name	Type	Required	Description
`task_id`	string	Yes	Task ID (obtained from the submission response)

Request Example:

Response Example (Queued):

{
 "task_id": "video_1234567890abcdef",
 "id": "video_1234567890abcdef",
 "object": "video_generation",
 "model": "sora-2",
 "status": "queued",
 "progress": 0,
 "created_at": 1704067200,
 "prompt": "A cute kitten playing in the garden, sunny and warm atmosphere",
 "seconds": "4",
 "size": "720x1280"
}

Response Example (In Progress):

{
 "task_id": "video_1234567890abcdef",
 "id": "video_1234567890abcdef",
 "object": "video_generation",
 "model": "sora-2",
 "status": "in_progress",
 "progress": 50,
 "created_at": 1704067200,
 "prompt": "A cute kitten playing in the garden, sunny and warm atmosphere",
 "seconds": "4",
 "size": "720x1280"
}

Response Example (Succeeded):

{
 "task_id": "video_1234567890abcdef",
 "id": "video_1234567890abcdef",
 "object": "video_generation",
 "model": "sora-2",
 "status": "succeeded",
 "progress": 100,
 "created_at": 1704067200,
 "completed_at": 1704067800,
 "prompt": "A cute kitten playing in the garden, sunny and warm atmosphere",
 "seconds": "4",
 "size": "720x1280",
 "width": 720,
 "height": 1280,
 "n_seconds": 4
}

Response Example (Failed):

{
 "task_id": "video_1234567890abcdef",
 "id": "video_1234567890abcdef",
 "object": "video_generation",
 "model": "sora-2",
 "status": "failed",
 "progress": 100,
 "created_at": 1704067200,
 "failure_reason": "Prompt contains inappropriate content",
 "error": {
  "message": "Prompt contains inappropriate content",
  "code": "content_policy_violation"
 }
}

Task Status Description:

Status Value	Description	Progress
`queued`	Task is queued, waiting for processing	0-20%
`in_progress`	Task is being processed	20-99%
`succeeded`	Task completed successfully	100%
`failed`	Task failed	100%

Important Notes:

When the task status is queued or in_progress, polling is required (query every 3-5 seconds is recommended).

When the status becomes succeeded, use the Task ID to download the video.

When the status becomes failed, check the failure_reason or error field for the cause of failure.

3. Download Video

Endpoint: GET /v1/video/generations/download?id={task_id}

Request Header:

Authorization: Bearer sk-xxxx

Query Parameters:

Parameter Name	Type	Required	Description
`id`	string	Yes	Task ID (must be a completed task)

Request Example:

Response Example:

{
 "success": true,
 "generation_id": "video_1234567890abcdef",
 "task_id": "video_1234567890abcdef",
 "format": "mp4",
 "size": 15728640,
 "base64": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQAAB...",
}

Response Field Description:

Field Name	Type	Description
`success`	boolean	Whether successful
`generation_id`	string	Generation ID (same as task_id)
`task_id`	string	Task ID
`format`	string	Video format (fixed as `"mp4"`)
`size`	number	Video file size (bytes)
`base64`	string	Base64 encoded video data

Usage Example:

JavaScript / HTML:

Python:

Complete Call Workflow

Workflow Example (Python)

Parameter Description

seconds (Video Duration)

Value	Description
`"4"`	4-second video (Default)
`"8"`	8-second video
`"12"`	12-second video

Note: Only the above three values are supported; other values will be automatically corrected to the default value "4".

size (Video Resolution)

Value	Description	Aspect Ratio
`"720x1280"`	Portrait (Default)	9:16
`"1280x720"`	Landscape	16:9

Note:

Only the above two resolutions are supported.

width and height parameters can be used; the system will automatically convert them to the size parameter.

If the provided width and height do not match the above resolutions, they will be automatically corrected to the default value "720x1280".

input_reference (Reference Image)

Supports two formats:

URL Format: "https://example.com/image.jpg"

Base64 Format: "data:image/jpeg;base64,/9j/4AAQSkZJRg..."

Supported Image Formats: JPEG, PNG

remix_from_video_id (Remix Mode)

Must be the task_id of a completed task.

Must start with video_.

When using Remix mode, only the prompt parameter is required; other parameters will be ignored.

Error Handling

Common Error Codes

HTTP Status Code	Error Message	Description
400	`invalid_request_error`	Request parameter error
401	`authentication_error`	API Key invalid or not provided
403	`permission_denied`	Permission denied
404	`not_found`	Task does not exist
429	`rate_limit_error`	Request frequency too high
500	`server_error`	Internal server error

Error Response Example

{
 "error": {
  "message": "Invalid API key",
  "type": "authentication_error",
  "code": "invalid_api_key"
 }
}

Best Practices

Polling Interval: It is recommended to query the task status every 3-5 seconds to avoid excessive requests.

Timeout Handling: Set a reasonable timeout (recommended 5-10 minutes) to avoid indefinite waiting.

Error Retry: For network errors or temporary errors, it is recommended to implement an exponential backoff retry mechanism.

Resource Cleanup: Clean up base64 data promptly after downloading to avoid excessive memory usage.

Asynchronous Processing: In server-side applications, it is recommended to use an asynchronous task queue to handle video generation requests.

Important Notes

⚠️ Quota Consumption: Video generation consumes a large amount of quota, currently 1s/$0.1; please ensure the account has sufficient balance.

⚠️ Task Retention: Generated task IDs are retained for 24 hours; please download the results in time.

⚠️ Prompt Restrictions: Prompts must not contain inappropriate content, otherwise the task will fail.

⚠️ Concurrency Limits: There may be limits on the number of concurrent tasks for a single account.

⚠️ File Size: The downloaded video file may be large; please pay attention to network bandwidth and storage space.

Document Version: v1.0
Last Updated: 2025-11-03

Overview#

Basic Information#

Supported Models#

API Endpoints#

1. Submit Video Generation Task#

2. Query Task Status#

3. Download Video#

Complete Call Workflow#

Workflow Example (Python)#

Parameter Description#

seconds (Video Duration)#

size (Video Resolution)#

input_reference (Reference Image)#

remix_from_video_id (Remix Mode)#

Error Handling#

Common Error Codes#

Error Response Example#

Best Practices#

Important Notes#