Skip to main content
POST
Submit Sora 2 Official Task
  1. After submission, a task_id will be returned. If you provided a callback_url, when the task status becomes finished or failed, a POST request will be sent to the callback_url.
  2. Regardless of whether callback_url is provided, you can retrieve the result through the unified Query Task Status endpoint.
sora-2-official supports text-to-video generation and optional single-image guided generation with fixed 4s, 8s, 12s, 16s, and 20s durations.

Models

  • sora-2-official - Text-to-video with optional reference image

Required parameters

  • prompt: Text prompt for video generation

Optional parameters

  • duration: 4, 8, 12, 16, or 20. Default is 4
  • aspect_ratio: 16:9 or 9:16. Default is 16:9
  • image_urls: Optional reference image array. Maximum 1 image

Notes

  • image_urls is optional. If provided, only one image is supported.
  • This page only describes the unified submit request. Query status through the standard task status API.

Authorizations

Authorization
string
header
required

All API endpoints require Bearer Token authentication.

Create an API key: sign in to PoYo, open Dashboard → API Key at poyo.ai/dashboard/api-key, and click to create a key.

Add it to the request header:

Body

application/json
model
enum<string>
required

Sora 2 Official model identifier

Available options:
sora-2-official
input
object
required
callback_url
string<uri>

Webhook callback URL for result notifications

Example:

"https://your-domain.com/callback"

Response

200 - application/json

Task submitted successfully

code
enum<integer>
required

Business status code. 200 means success; any other value means the request failed. Always check this field: some validation errors return HTTP 200 with code: 400 in the body.

  • 200: Success
  • 400: Invalid request parameters
  • 401: Missing or invalid API key
  • 402: Insufficient credits
  • 403: Permission denied
  • 404: Resource not found
  • 408: Request timeout
  • 429: Rate limit exceeded
  • 500: Internal server error
  • 502: Upstream service error
  • 503: Service unavailable

See Error Codes for details.

Available options:
200,
400,
401,
402,
403,
404,
408,
429,
500,
502,
503
Example:

200

data
object
required