Skip to main content

​
Request

curl -X POST "https://api.znapai.com/v1/videos" \
  -H "Authorization: Bearer $ZnapAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A cinematic drone shot flying through a futuristic cyberpunk city at night, volumetric lighting, realistic reflections, neon signs, rain-soaked streets",
    "size": "1280x720",
    "seconds": "4",
    "metadata": {
      "user_id": "test-user",
      "project": "video-api-testing"
    }
  }'

​
Parameters

​
Required Parameters

​
model
string
required
The video generation model identifier. Supported value: "sora-2".
​
prompt
string
required
A text description of the video you want to generate.

​
Optional / Strict Parameters

OpenAI’s Sora validation is incredibly strict. Passing incorrect data types (like an integer instead of a string) or unsupported resolutions will result in a 400 Bad Request.
​
seconds
string
The duration of the video clip in seconds. Must be a string. Supported values: "4", "8", "12".
​
size
string
The output resolution formatted as widthxheight. Supported values: "720x1280", "1280x720", "1024x1792", "1792x1024".
​
input_reference
string
An optional image reference (URL or base64 data) used to guide generation for Image-to-Video workflows.
​
metadata
object
Optional metadata attached to the request for tracking, analytics, user identification, or application-specific context. Any valid JSON object is supported.

​
Metadata Example

{
  "metadata": {
    "project": "video-api-testing",
    "user_id": "test-user-id-123",
    "environment": "staging"
  }
}

​
Get Video Status

The POST /v1/videos request returns a video job id. Use this id to poll the status of your generation job. 
curl https://api.znapai.com/v1/videos/$VIDEO_ID \
  -H "Authorization: Bearer $ZnapAI_API_KEY"

​
200 Response Example

{
  "id": "id",
  "completed_at": 0,
  "created_at": 0,
  "error": {
    "code": "code",
    "message": "message"
  },
  "expires_at": 0,
  "model": "string",
  "object": "video",
  "progress": 0,
  "prompt": "prompt",
  "remixed_from_video_id": "remixed_from_video_id",
  "seconds": "seconds",
  "size": "720x1280",
  "status": "queued"
}
The status field indicates the current state of the video job. Possible values include "queued", "in_progress", and "completed". Poll this endpoint until status changes to "completed" before downloading the video.

​
Download Video Content

Once the video job status is "completed", download the generated video bytes or a derived preview asset using this endpoint. Streams the rendered video content for the specified video job.

​
Path Parameters

​
video_id
string
required
The unique identifier of the completed video job.
curl https://api.znapai.com/v1/videos/$VIDEO_ID/content \
  -H "Authorization: Bearer $ZnapAI_API_KEY"

​
Common Errors to Avoid

Due to an exception mapping quirk, if you violate any of OpenAI’s parameter validations (e.g., passing "duration" instead of "seconds"), the proxy may wrap the OpenAI 400 Bad Request inside a confusing ContentPolicyViolationError.
  • Passing duration instead of seconds: OpenAI expects "seconds". It does not recognize "duration".
  • Passing seconds as an integer: You must pass "seconds": "4", not "seconds": 4.
  • Passing an unsupported size: Using standard sizes like "1920x1080" will fail. You must use the specific crop ratios allowed by OpenAI (e.g., "1280x720").