Sora Video Generation — Create Task API Reference Guide

POST /v1/sora/videos — Generate 4, 8, or 12-second videos with OpenAI Sora. Set model, aspect ratio, duration, and optionally attach a reference image.

Use this endpoint to submit a new video generation task with OpenAI’s Sora model. You supply a prompt, choose your model variant, set the duration and aspect ratio, and optionally attach a reference image to guide the visual style. The API responds immediately with a task id — you then poll the Query Video Task endpoint until the video is ready.

Video generation is asynchronous. The create endpoint returns a task id with status: "queued". Use the Query Video Task endpoint to check progress and retrieve the final video_url.

Base URL & Endpoint

Base URL:  https://zcbservice.aizfw.cn/kyyReactApiServer
Endpoint:  POST /v1/sora/videos
Full URL:  https://zcbservice.aizfw.cn/kyyReactApiServer/v1/sora/videos

All requests must include your API key as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Supported Models

Model	Supported Durations	Notes
openAiSora2Plus	4 s · 8 s · 12 s	Enhanced version
openAiSora2Pro	4 s · 8 s · 12 s	Higher-quality generation

Request Parameters

model · string · required

The Sora model to use. Accepted values:

• openAiSora2Plus — enhanced model, supports 4, 8, 12-second videos
• openAiSora2Pro — higher-quality model, supports 4, 8, 12-second videos

prompt · string · required

A text description of the video you want to generate. Be specific about the scene, style, motion, and lighting.

Example: "A cat dancing in the rain, cinematic style"

size · string

Video resolution. Use this or aspect_ratio — not both.

• 720x1280 — portrait (default)
• 1280x720 — landscape

Only these two resolutions are supported. The image orientation of any reference image must match the chosen size.

aspect_ratio · string

Video aspect ratio. Use this or size — not both.

• 16:9 — landscape
• 9:16 — portrait

duration · integer

Video duration in seconds. Accepted values: 4, 8, 12.

Use this or seconds — not both.

seconds · integer

Video duration in seconds. Accepted values: 4, 8, 12.

Use this or duration — not both.

input_reference · array

An array of reference image URLs to guide video style and content. Maximum 1 image.

Use this or image_urls — not both.

Constraints:

• Do not use real portrait photographs — these will likely cause generation failures.
• Image dimensions must match the chosen ratio: 1280×720 for 16:9, or 720×1280 for 9:16.

image_urls · array

An array of reference image URLs to guide video style and content. Maximum 1 image.

Use this or input_reference — not both.

Constraints:

• Do not use real portrait photographs — these will likely cause generation failures.
• Image dimensions must match the chosen ratio: 1280×720 for 16:9, or 720×1280 for 9:16.

Response Fields

id · string

Unique identifier for the video generation task. Save this value — you will use it to poll the Query Video Task endpoint.

object · string

Object type. Always "video.generation".

created · integer

Unix timestamp (seconds) of when the task was created.

model · string

The model name you specified in the request.

status · string

Initial task status. On successful creation this is always "queued".

error · string

Error message. Only present when status is "failed".

Code Examples

cURL

curl --request POST \
  --url https://zcbservice.aizfw.cn/kyyReactApiServer/v1/sora/videos \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "openAiSora2Plus",
    "prompt": "A cat dancing in the rain, cinematic style",
    "aspect_ratio": "16:9",
    "seconds": 8,
    "input_reference": [
      "https://example.com/reference1.jpg"
    ]
  }'

Example success response:

{
  "id": "sora_abc123def456",
  "object": "video.generation",
  "created": 1761635478,
  "model": "openAiSora2Plus",
  "status": "queued"
}

Parameter Mutual Exclusivity

Group	Choose one
Resolution	size or aspect_ratio
Duration	duration or seconds
Reference image	input_reference or image_urls

Tips

Write better prompts — include a specific scene description, style keywords (e.g. "cinematic", "artistic", "realistic"), motion descriptions, and lighting preferences for best results.

Avoid real portrait photos as reference images. The Sora model does not support realistic human faces and such requests will almost always fail. Use stylised or illustrated imagery instead.

After creating a task, poll the Query Video Task endpoint every 30–60 seconds. A typical 8-second video takes 2–5 minutes to generate.