> ## Documentation Index > Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Sora 2 > OpenAI video generation API for text-to-video and image-to-video workflows ## Overview Sora 2 is an OpenAI video model for text-to-video and single-image-to-video workflows. Use this page when you are ready to call the API after trying the model in the APIXO playground. | Capability | Value | | ---------------- | ---------------------------------- | | Model ID | `sora-2` | | Modes | `text-to-video`, `image-to-video` | | Prompt length | 1-10000 characters | | Reference images | Exactly 1 URL for `image-to-video` | | Aspect ratios | `landscape`, `portrait` | | Durations | `4`, `8`, `12` seconds | | Output format | MP4 video URLs | ## Endpoint and authentication Base URL: ```text theme={null} https://api.apixo.ai/api/v1 ``` | Method | Endpoint | Purpose | | ------ | ------------------------------------ | ------------------------------------- | | `POST` | `/generateTask/sora-2` | Submit a generation task | | `GET` | `/statusTask/sora-2?taskId={taskId}` | Poll task status and retrieve results | All requests require your APIXO API key: ```http theme={null} Authorization: Bearer YOUR_API_KEY ``` Submit requests also require: ```http theme={null} Content-Type: application/json ``` ## Copy-paste async quickstart This minimal request submits a text-to-video task and returns a `taskId`. ```bash theme={null} curl -X POST "https://api.apixo.ai/api/v1/generateTask/sora-2" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "request_type": "async", "input": { "mode": "text-to-video", "prompt": "a cinematic flyover of a futuristic city at sunrise, golden hour lighting, slow camera movement", "duration": 12, "aspect_ratio": "landscape" } }' ``` Successful response: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678" } } ``` Save the `taskId`; you need it to poll for the final result. ## Poll for result ```bash theme={null} curl -X GET "https://api.apixo.ai/api/v1/statusTask/sora-2?taskId=task_12345678" \ -H "Authorization: Bearer YOUR_API_KEY" ``` Processing response: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678", "state": "processing", "createTime": 1767965610929 } } ``` Success response: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678", "state": "success", "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/video.mp4\"]}", "createTime": 1767965610929, "completeTime": 1767965932317, "costTime": 321388 } } ``` Failed response: ```json theme={null} { "code": 200, "message": "success", "data": { "taskId": "task_12345678", "state": "failed", "failCode": "SensitiveContentDetected", "failMsg": "Your content was flagged by OpenAI as violating content policies.", "createTime": 1767965610929, "completeTime": 1767965630132 } } ``` Parse `resultJson` after `state` becomes `success`: ```javascript theme={null} const payload = JSON.parse(data.resultJson); const videoUrls = payload.resultUrls; ``` ## Request body ### Text-to-video ```json theme={null} { "request_type": "async", "input": { "mode": "text-to-video", "prompt": "a slow aerial shot over a futuristic coastal city at sunset", "duration": 12, "aspect_ratio": "landscape", "remove_watermark": true } } ``` ### Image-to-video ```json theme={null} { "request_type": "async", "input": { "mode": "image-to-video", "prompt": "animate this portrait with a smooth camera push-in and soft cinematic lighting", "image_urls": [ "https://example.com/source.jpg" ], "duration": 8, "aspect_ratio": "portrait", "remove_watermark": true } } ``` ## Parameters Result delivery mode. Use `async` for polling with `statusTask`, or `callback` for webhook delivery. Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive the final task payload. See [Webhooks](/api-reference/webhooks). Sora 2 input parameters. Generation mode. Supported values: `text-to-video`, `image-to-video`. Text prompt describing the desired video. Supports 1-10000 characters. Output video duration in seconds. Supported values: `4`, `8`, `12`. Reference image URLs. Required for `image-to-video`. Must contain exactly 1 public image URL. Output aspect ratio. Supported values: `landscape`, `portrait`. Whether to request watermark removal when the selected route supports it. ## Response format ### Submit task response `POST /generateTask/sora-2` returns a task ID when the task is accepted: API status code. `200` means the task was accepted. Human-readable status message. Unique task identifier used with the status endpoint. ### Status response fields Unique task identifier. Current task state: `pending`, `processing`, `success`, or `failed`. JSON string containing generated video URLs. Present when `state` is `success`. Machine-readable failure code. Present when `state` is `failed`. Human-readable failure message. Present when `state` is `failed`. Task creation timestamp in Unix milliseconds. Task completion timestamp in Unix milliseconds. Present after completion. Processing duration in milliseconds. Present after successful completion. ## Webhook callback mode Use callback mode when your backend should receive the final result automatically instead of polling. ```bash theme={null} curl -X POST "https://api.apixo.ai/api/v1/generateTask/sora-2" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "request_type": "callback", "callback_url": "https://your-server.com/webhooks/apixo", "input": { "mode": "image-to-video", "prompt": "extend this scene into a gentle handheld camera move with realistic ambient motion", "image_urls": [ "https://example.com/source.jpg" ], "duration": 8, "aspect_ratio": "portrait" } }' ``` See [Webhooks](/api-reference/webhooks) for delivery requirements and retry behavior. ## Billing Sora 2 is billed by generated video duration. The current public APIXO price on the pricing page is `$0.09 / second`. | Duration | APIXO price | | ------------ | --------------- | | `4` seconds | `$0.36 / video` | | `8` seconds | `$0.72 / video` | | `12` seconds | `$1.08 / video` | For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing). ## Latency and polling Actual latency may vary by prompt complexity, selected route, input image availability, and current queue load. | Duration | Typical generation time | Recommended first poll | Poll interval | | ------------ | ----------------------- | ------------------------ | ------------- | | `4` seconds | 2-4 minutes | 120s after task creation | 10s | | `8` seconds | 3-5 minutes | 180s after task creation | 10s | | `12` seconds | 4-6 minutes | 180s after task creation | 10s | For production video workloads, use callback mode to avoid frequent polling while long-running tasks are queued or rendering. Rate limits and concurrency can vary by account, API key, and route. If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](/api-reference/system). ## Errors and troubleshooting ### HTTP errors | Code | Meaning | What to do | | ----- | ----------------------------------------------------------------- | ------------------------------------------------ | | `400` | Invalid request body, mode, parameter, prompt, or image URL shape | Fix the request before retrying | | `401` | Missing or invalid API key | Check the `Authorization` header | | `402` | Insufficient balance or quota | Add balance before retrying | | `403` | Key or route cannot access the model | Check permissions and route strategy | | `429` | Rate limit or concurrency limit reached | Retry with exponential backoff | | `500` | Server error or unmapped upstream failure | Retry with backoff | | `502` | Upstream service error | Retry with backoff | | `504` | Upstream timeout | Retry or use callback mode for long-running jobs | ### Task failure codes Failure codes can vary by selected route. Common values include: | Fail code | Meaning | What to do | | ------------------------------------ | ---------------------------------------------- | ------------------------------------------------------- | | `PromptInvalid` | Prompt was rejected or malformed | Rewrite the prompt and retry | | `SensitiveContent` | Prompt or media failed safety checks | Change the prompt or input image | | `SensitiveContentDetected` | Upstream flagged generated or input content | Change the prompt or input image | | `InputImageSensitiveContentDetected` | Reference image failed safety checks | Use a different public image URL | | `ImageFormatIncorrect` | Reference image format could not be processed | Use a direct JPG, PNG, or WebP image URL | | `InvalidImageSize` | Reference image dimensions or size are invalid | Resize or compress the image | | `RateLimited` | Upstream route was rate limited | Retry with exponential backoff | | `Timeout` | Generation did not finish in time | Retry, reduce prompt complexity, or use callback mode | | `Unknown error` | Upstream returned an unmapped failure | Retry with backoff or contact support with the `taskId` | See [Error Codes](/api-reference/errors) for the full error reference. ## Related links * [Generation API Overview](/models) * [Generate Task](/api-reference/generate-task) * [Status Task](/api-reference/status-task) * [Webhooks](/api-reference/webhooks) * [Error Codes](/api-reference/errors) * [Parameter Specification](/api-reference/parameters) * [Routing Strategies](/concepts/routing-strategies) * [Pricing](https://apixo.ai/pricing)