Omni video generation

Call to generate text-to-video, image-to-video, first-and-last-frame, and multi-reference-image videos.

POST /v1/videos

Available models

Headers

Name	Type	Required	Description
	string	Yes	Request authentication. Use a Bearer Token, for example: .
	string	Yes	Request content type. Must be set to .

Request body

Name	Type	Required	Description
	string	Yes	Model name. See Available models above.
	string	Yes	Video prompt. Example: .
	string	No	Video duration. Prefer a string; recommended range is to seconds. Example: .
	string	No	Aspect ratio. Example values: , .
	string	No	Resolution. Example values: , , , .
	string	No	First-frame image. When set, enters first-frame image-to-video mode. Supports a public URL or . Example: .
	string	No	Last-frame image. Must be used together with . Example: .
	array<string>	No	Multi-reference image list, up to 5 images. Supports a public URL or . Example: .

Request example

Text-to-video

curl -X POST https://octopusx.ai/v1/videos \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '
{
  "model": "omni-fast",
  "prompt": "Ocean waves gently rolling onto a sandy beach at golden hour, cinematic, warm sunlight",
  "seconds": "8",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

First-frame video

curl -X POST https://octopusx.ai/v1/videos \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '
{
  "model": "omni-fast",
  "prompt": "The scene comes alive with gentle wind and drifting clouds",
  "first_image_url": "https://example.com/first-frame.jpg",
  "seconds": "8",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

First-and-last-frame video

curl -X POST https://octopusx.ai/v1/videos \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '
{
  "model": "omni-fast",
  "prompt": "Create a smooth transition from the first frame to the last frame.",
  "first_image_url": "https://example.com/first-frame.jpg",
  "last_image_url": "https://example.com/last-frame.jpg",
  "seconds": "8",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

Reference video

curl -X POST https://octopusx.ai/v1/videos \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '
{
  "model": "omni-fast",
  "prompt": "Use the first image as the character reference and the second image as the visual style reference. Create a cozy cafe conversation scene.",
  "images": [
    "https://example.com/character.jpg",
    "https://example.com/style.jpg"
  ],
  "seconds": "8",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

Response example

200 - Submitted

{
  "id": "video_abc123",
  "task_id": "video_abc123",
  "object": "video",
  "model": "omni-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1735689600,
  "video_url": ""
}

200 - Task query success

{
  "id": "video_abc123",
  "task_id": "video_abc123",
  "object": "video",
  "model": "omni-fast",
  "status": "completed",
  "progress": 100,
  "created_at": 1735689600,
  "completed_at": 1735689900,
  "video_url": "https://example.com/results/omni-fast.mp4"
}

200 - Task failed

{
  "id": "video_abc123",
  "task_id": "video_abc123",
  "object": "video",
  "model": "omni-fast",
  "status": "failed",
  "progress": 100,
  "error": {
    "message": "upstream task failed",
    "code": "task_failed"
  }
}

400 - Invalid parameters

{
  "error": {
    "message": "field model is required",
    "type": "invalid_request_error",
    "param": "model",
    "code": "invalid_request_error"
  }
}

401 - Auth failed

{
  "error": {
    "message": "invalid token",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

402 - Insufficient quota

{
  "error": {
    "message": "insufficient quota",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

429 - Too many requests

{
  "error": {
    "message": "rate limit exceeded",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

500 - Server error

{
  "error": {
    "message": "internal server error",
    "type": "server_error",
    "code": "server_error"
  }
}

Response fields

Name	Type	Description
	string	Video task ID. Can be used later for task query.
	string	Compatibility field for the video task ID. Usually the same as .
	string	Object type, typically .
	string	Model used for this task, e.g. .
	string	Task status. Common values: , , , .
	number	Task progress, typically from to .
	string	Video URL when complete.
	object	Error object on task failure or API error, usually including and .

Related endpoints

• Omni video overview
• Video APIs overview
• Error codes