Skip to main content
POST
https://octopusx.ai
/
v1
/
videos
OpenAI-Compatible Video Interface
curl --request POST \
  --url https://octopusx.ai/v1/videos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "task_id": "<string>",
  "video_id": "<string>",
  "model": "<string>",
  "prompt": "<string>",
  "image": "<string>",
  "seconds": "<string>",
  "size": "<string>",
  "metadata": {}
}
'
{
  "id": "video_abc123",
  "task_id": "video_abc123",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1735689600,
  "seconds": "5",
  "size": "1280x720"
}

​
OpenAI-Compatible Video Interface

This set of routes presents itself externally in an OpenAI Videos API style, suitable for clients that already read and write results as video objects.
  • Creation, querying, and remix all use the OpenAI-style video object.
  • The exposed id maps to the platform task ID, rather than directly exposing the upstream raw task ID.
  • The content proxy route supports access via API Key and logged-in session state.
  • Remix will preferentially look up the original video task and lock execution to the original channel.

​
Route List

MethodPathDescription
POST/v1/videosCreate a video task
GET/v1/videos/{task_id}Query a video task
POST/v1/videos/{video_id}/remixRemix based on an existing video task
GET/v1/videos/{task_id}/contentProxy download of video content

​
Request Examples

curl -X POST https://octopusx.ai/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A paper airplane flies through a bright office, with the camera smoothly following",
    "seconds": "5",
    "size": "1280x720"
  }'

​
Response Examples

{
  "id": "video_abc123",
  "task_id": "video_abc123",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1735689600,
  "seconds": "5",
  "size": "1280x720"
}

​
Authentication

Creation, querying, and remix use Bearer Token: 
Authorization: Bearer YOUR_API_KEY
GET /v1/videos/{task_id}/content also supports:
  • Authorization: Bearer YOUR_API_KEY
  • Web dashboard login state UserAuth

​
Path Parameters

​
task_id
string
required
Video task ID, used for querying and content proxying.
​
video_id
string
required
The source video ID for remix. The server will first look up the original task and original channel using it.

​
Body

​
model
string
required
Video model name, such as sora-2, sora_video2, or a model name mapped from another channel.
​
prompt
string
required
Video description or remix instruction.
​
image
string
Input image for image-to-video generation. Support depends on the specific upstream provider.
​
seconds
string
Target video duration, common values are 5, 10, and 15.
​
size
string
Target resolution or ratio, such as 1280x720, 720x1280, or 16:9.
​
metadata
object
Vendor passthrough parameters. For remix, upstream proprietary fields can also be included here.

​
Response

​
id
string
Public video task ID.
​
status
string
Task status, common values are queued, in_progress, completed, and failed.
​
video_url
string
Playable URL after generation is complete. In many cases, it points to the platform proxy route.
​
error
object
Error details for failed tasks, shown only when status = failed.

​
Usage Scenarios

​
Query a Task

curl https://octopusx.ai/v1/videos/video_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Remix

curl -X POST https://octopusx.ai/v1/videos/video_abc123/remix \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "Keep the composition, but change the scene to a neon-lit nighttime style"
  }'

​
Proxy Download

curl -L https://octopusx.ai/v1/videos/video_abc123/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output output.mp4

​
Notes

If you have both /v1/video/generations and /v1/videos integrated, it is recommended that the frontend consistently choose one response structure to use, and avoid mixing the generic task wrapper and the OpenAI video object within the same parsing logic.