Omni reference video generation

Call for reference-video editing, extension, or regeneration.

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 edit or generation prompt. Specify which motion, camera, or subject to keep, and clearly ask for a new video output. Example: .
	string	No	Reference video. Supports a public MP4 URL or . Use one of , , or . Example: .
	string	No	Compatibility alias for . Use when is not set. Example: .
	string	No	Compatibility alias for . Use when and are not set. Example: .
	string	No	Output duration. Prefer a string; recommended range is to seconds. Example: .
	string	No	Aspect ratio. Example values: , .
	string	No	Resolution. Example values: , , , .
	string	No	Compatibility first-frame field from . Without a reference video, prefer directly. Example: .
	array<string>	No	Compatibility multi-reference image field from , up to 5 images. Without a reference video, prefer directly.

Request example

video reference

curl -X POST https://octopusx.ai/v1/videos \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '
{
  "model": "omni-fast-v2v",
  "prompt": "Edit the attached video into a visibly new version while preserving the original camera path, timing, subject motion, and shot continuity. Add a rainy cinematic night look with neon reflections. Output a newly generated video, not the uploaded source clip or its preview.",
  "video": "https://example.com/source.mp4",
  "seconds": "8",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

video_url alias

curl -X POST https://octopusx.ai/v1/videos \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '
{
  "model": "omni-fast-v2v",
  "prompt": "Extend this clip into a new cinematic shot with the same camera path.",
  "video_url": "https://example.com/source.mp4",
  "seconds": "8",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

input_video alias

curl -X POST https://octopusx.ai/v1/videos \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '
{
  "model": "omni-fast-v2v",
  "prompt": "Regenerate the attached clip with brighter lighting and smoother motion.",
  "input_video": "https://example.com/source.mp4",
  "seconds": "8",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

Response example

200 - Submitted

{
  "id": "video_abc123",
  "task_id": "video_abc123",
  "object": "video",
  "model": "omni-fast-v2v",
  "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-v2v",
  "status": "completed",
  "progress": 100,
  "created_at": 1735689600,
  "completed_at": 1735689900,
  "video_url": "https://example.com/results/omni-fast-v2v.mp4"
}

200 - Task failed

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

400 - Invalid parameters

{
  "error": {
    "message": "video is required for V2V generation",
    "type": "invalid_request_error",
    "param": "video",
    "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"
  }
}

413 - Request body too large

{
  "error": {
    "message": "request body too large",
    "type": "invalid_request_error",
    "code": "request_body_too_large"
  }
}

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