AI Video APIAI Video API

Sora 2

OpenAI Sora 2 video generation model. Generate high-quality AI videos from text or image prompts, with durations of 4, 8, or 12 seconds.

Model

Model NameDurationAspect Ratios
sora-24s, 8s, 12s16:9, 9:16

Pricing

Per-second billing: 25 credits/s ($0.125/s).

DurationCreditsPrice
4s100 credits$0.50
8s200 credits$1.00
12s300 credits$1.50

Create Task

POST https://api.aivideoapi.ai/v1/videos/generations

Request Body

FieldTypeRequiredDescription
modelstringYesMust be sora-2
inputobjectYesGeneration parameters, see below
callback_urlstringNoURL to receive task completion/failure notifications

Input Object

FieldTypeRequiredDescription
promptstringYesText description (max 5000 characters)
durationintegerYesVideo duration in seconds: 4, 8, or 12
aspect_ratiostringYesAspect ratio: 16:9 (landscape) or 9:16 (portrait)
image_urlsstring[]NoFirst-frame image URL for image-to-video mode (only 1 image allowed)

Example: Text-to-Video

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "input": {
      "prompt": "A drone shot flying over mountains at sunset, cinematic lighting",
      "duration": 8,
      "aspect_ratio": "16:9"
    }
  }'

Example: Image-to-Video

Provide an image as the first frame. The model generates a video based on the image and prompt.

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "Camera slowly pushes in, the person turns and smiles",
      "duration": 4,
      "aspect_ratio": "9:16",
      "image_urls": ["https://example.com/photo.jpg"]
    }
  }'

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "cbf6b69d-4f03-4817-8ed7-94c0292184a8"
  }
}

Query Task

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

Status transitions: pending -> processing -> completed or failed.

Processing

{
  "id": "e717a5ee-2ed4-47f4-8cc3-53394f1abb35",
  "status": "processing",
  "model": "sora-2",
  "created_at": 1774706165,
  "progress": null
}

Completed

{
  "id": "7d89c51e-9430-410e-909e-df347131ebaa",
  "status": "completed",
  "model": "sora-2",
  "created_at": 1774790227,
  "completed_at": 1774796529,
  "output": {
    "urls": [
      "https://your-r2-bucket.example.com/videos/2026/04/02/7d89c51e.mp4?..."
    ],
    "metadata": {
      "duration": 8,
      "prompt": "A drone shot flying over mountains at sunset, cinematic lighting"
    }
  }
}

Video URLs expire in 24 hours. Download promptly after generation completes.

Failed

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "sora-2",
  "created_at": 1774793758,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

When a task fails, pre-charged credits are automatically refunded.

Callback

Pass callback_url when creating the task. The system will automatically send a POST request to your URL when the task completes or fails.

On Task Completed

{
  "id": "7d89c51e-9430-410e-909e-df347131ebaa",
  "status": "completed",
  "model": "sora-2",
  "created_at": 1774790227,
  "completed_at": 1774796529,
  "output": {
    "urls": [
      "https://your-r2-bucket.example.com/videos/2026/04/02/7d89c51e.mp4?..."
    ],
    "metadata": {
      "duration": 8,
      "prompt": "A drone shot flying over mountains at sunset, cinematic lighting"
    }
  }
}

On Task Failed

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "sora-2",
  "created_at": 1774793758,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

When a task fails, pre-charged credits are automatically refunded.

Input Requirements

Image (First Frame)

  • Formats: JPEG, PNG, WebP
  • Max size: 10 MB
  • Aspect ratio: 2:5 ~ 5:2
  • Dimensions: min 300px on shortest side

Error Codes

When a request fails, the API returns a JSON error response:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

Error Reference

HTTP StatusCodeTypeDescription
400invalid_requestinvalid_request_errorMissing or invalid parameters
401invalid_api_keyauthentication_errorAPI key is invalid, disabled, or deleted
402insufficient_creditsbilling_errorCredit balance too low, please top up
403ip_not_allowedpermission_errorRequest IP not in the key's allowlist
404model_not_foundinvalid_request_errorModel does not exist or is inactive
404task_not_foundinvalid_request_errorTask ID does not exist
429rate_limit_exceededrate_limit_errorToo many requests, please slow down
429spend_limit_exceededbilling_errorKey spend limit reached (hourly/daily/total)
500internal_errorapi_errorUnexpected server error
503upstream_errorupstream_errorUpstream AI provider returned an error

Common Scenarios

invalid_request (400)

Returned when required fields are missing or invalid.

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

Your balance is too low. Check your balance with GET /v1/credits and top up in Dashboard > Billing.

invalid_api_key (401)

Possible causes:

  • The key does not start with sk-
  • The key has been disabled or deleted
  • The user account has been banned

upstream_error (503)

The upstream AI provider returned an error. This may happen when:

  • The input contains sensitive or prohibited content
  • The provider is temporarily unavailable
  • The request parameters are not supported by the provider

Credits are automatically refunded when a task fails due to upstream errors.