Skip to main content
POST
https://octopusx.ai
/
v1
/
videos
curl -X POST https://octopusx.ai/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -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"
  }'

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

​
omni-fast-v2v

omni-fast-v2v submits asynchronous video tasks with a JSON request body, suitable for editing, extending, or regenerating an existing MP4 as a reference video.
  • Asynchronous processing mode; returns id or task_id after submission.
  • The reference video field supports video, video_url, and input_video.
  • The reference video supports a public MP4 URL or data:video/mp4;base64,....
  • The reference video is up to 15MB.
  • When a reference video is not needed, prefer omni-fast.

​
Method and Path

POST /v1/videos

​
Request Examples

curl -X POST https://octopusx.ai/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -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"
  }'

​
Response Examples

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

​
Authentication

Use Bearer Token authentication: 
Authorization: Bearer YOUR_API_KEY
All request examples must include the Authorization header. JSON requests must also include: 
Content-Type: application/json

​
Body

​
model
string
required
Fixed value omni-fast-v2v. Example: "omni-fast-v2v".
​
prompt
string
required
Video editing or generation prompt. It is recommended to state which motion, camera, or subject to preserve, and explicitly request a newly generated video. Example: "Edit the attached video into a visibly new version".
​
video
string
Reference video. Supports a public MP4 URL or data:video/mp4;base64,.... Choose one of video, video_url, input_video. Example: "https://example.com/source.mp4".
​
video_url
string
Compatibility field for video. Can be used when video is not provided. Example: "https://example.com/source.mp4".
​
input_video
string
Compatibility field for video. Can be used when neither video nor video_url is provided. Example: "https://example.com/source.mp4".
​
seconds
string
Output duration. Recommended as a string; recommended range is 4 to 30 seconds. Example: "8".
​
aspect_ratio
string
Aspect ratio. Example values: "16:9", "9:16".
​
resolution
string
Resolution field. Example values: "720p", "1080p", "2k", "4k".
​
first_image_url
string
First frame image field compatible with omni-fast. When there is no reference video, prefer omni-fast. Example: "https://example.com/first-frame.jpg".
​
images
array<string>
Multi-reference image field compatible with omni-fast, up to 5. When there is no reference video, prefer omni-fast.

​
Response

​
id
string
Video task ID. Can be used later for GET /v1/videos/{task_id} queries.
​
task_id
string
Compatibility field for the video task ID. Usually the same as id.
​
object
string
Object type, usually video.
​
model
string
The model used for this task, for example omni-fast-v2v.
​
status
string
Task status. Common values are queued, in_progress, completed, failed.
​
progress
number
Task progress, commonly in the range 0 to 100.
​
video_url
string
The video URL after completion.
​
error
object
The error object returned when a task fails or an API error occurs, usually containing message and code.

​
Use Cases

​
Public MP4 Reference Video

{
  "model": "omni-fast-v2v",
  "prompt": "Extend this clip into a new cinematic shot with the same camera path.",
  "video": "https://example.com/source.mp4",
  "seconds": "8",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}

​
Local MP4 to data URI

import base64
from pathlib import Path

source = Path("source.mp4")
if source.stat().st_size > 15 * 1024 * 1024:
    raise ValueError("Reference video must be at most 15MB")

video = "data:video/mp4;base64," + base64.b64encode(source.read_bytes()).decode("ascii")

​
Using the input_video alias

{
  "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"
}

​
Notes

  • omni-fast does not support reference video; V2V must use omni-fast-v2v.
  • The reference video is up to 15MB; when too large, compress it first or convert to a public URL.
  • video, video_url, input_video are the same kind of reference-video input; prefer video.
  • For data:video/mp4;base64,..., the actual request body grows larger, so allow for network timeout.
  • After completion, retrieve the generated MP4 from the returned video_url.