Video and Asynchronous Task Interfaces

Video generation is typically an asynchronous task: after submitting a request, you first receive a task ID, then poll the task status, and retrieve the video or task output upon success.

Video Interface Selection

Interface	Description	Recommendation
/v1/videos	OpenAI-style video task submission	Priority for new integrations, requires matching video task adapter
/v1/videos/{task_id}	OpenAI-style video task query	Used with /v1/videos
/v1/videos/{task_id}/content	Get video content or output proxy	Depends on whether channel provides output
/v1/video/generations	Compatible video task submission path	Legacy client compatibility
/v1/video/generations/{task_id}	Compatible video task query path	Legacy client compatibility
/v1/videos/{video_id}/remix	Regenerate based on existing video	Conditional support, requires channel support

The routing for /v1/videos and /v1/video/generations may exist, but this doesn't mean the current instance has configured available video task models. The service needs matching video task channels or task plugins; otherwise it may return capability not supported, model not found, or only a generic task receipt rather than a complete video object.

OpenAI-Style Video Submission

export COREROUTER_API_KEY="sk-xxxxxxxxxxxxxxxx"

curl https://api.corerouter.cloud/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COREROUTER_API_KEY" \
  -d '{
    "model": "video-model-id",
    "prompt": "An orange cat playing piano on stage, cinematic lighting",
    "seconds": "4",
    "size": "1280x720"
  }'

If the channel supports image-to-video, you can pass an image URL:

curl https://api.corerouter.cloud/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COREROUTER_API_KEY" \
  -d '{
    "model": "video-model-id",
    "prompt": "Make the subject in the image slowly turn around",
    "image": "https://example.com/input.jpg",
    "seconds": "4",
    "size": "1280x720"
  }'

You can also use multipart/form-data, with field names typically including model, prompt, input_reference, seconds, and size:

curl https://api.corerouter.cloud/v1/videos \
  -H "Authorization: Bearer $COREROUTER_API_KEY" \
  -F "model=video-model-id" \
  -F "prompt=Make the subject in the image slowly turn around" \
  -F "[email protected]" \
  -F "seconds=4" \
  -F "size=1280x720"

Query Video Task

After successful submission, the response typically includes id or task_id. Use the returned task ID to query:

curl https://api.corerouter.cloud/v1/videos/task_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $COREROUTER_API_KEY"

Common statuses:

Status	Meaning
queued	Submitted, awaiting processing
in_progress	Generating
completed	Completed
failed	Failed, check error

Get Video Content

If the task channel supports output proxy, you can access:

curl -L https://api.corerouter.cloud/v1/videos/task_xxxxxxxxxxxxxxxx/content \
  -H "Authorization: Bearer $COREROUTER_API_KEY" \
  --output output.mp4

Whether content can be directly downloaded depends on the video channel and task plugin. Some channels only return a result URL, which needs to be read from the query result.

Compatible Video Interface

Existing clients using /v1/video/generations can continue to call this way:

curl https://api.corerouter.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COREROUTER_API_KEY" \
  -d '{
    "model": "video-model-id",
    "prompt": "City night timelapse photography",
    "seconds": "5",
    "size": "1280x720"
  }'

Compatible paths primarily read generic fields: model, prompt, seconds, duration, size, image, images, input_reference, and metadata. Fields like width, height, fps, seed will not automatically convert to size; don't pass only these fields expecting server-side video dimension inference.

Query:

curl https://api.corerouter.cloud/v1/video/generations/task_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $COREROUTER_API_KEY"

Generic Task Interface

/v1/tasks/{key} is a lower-level generic task submission entry point. key represents a task plugin or task type; regular users don't need to guess this value directly.

curl https://api.corerouter.cloud/v1/tasks/task-plugin-key \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COREROUTER_API_KEY" \
  -d '{
    "model": "task-model-id",
    "prompt": "Generate a demo task",
    "metadata": {
      "quality": "standard"
    }
  }'

Query generic task:

curl https://api.corerouter.cloud/v1/tasks/task_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $COREROUTER_API_KEY"

Query task artifacts:

curl https://api.corerouter.cloud/v1/tasks/task_xxxxxxxxxxxxxxxx/artifacts \
  -H "Authorization: Bearer $COREROUTER_API_KEY"

Download specific artifact:

curl -L https://api.corerouter.cloud/v1/tasks/task_xxxxxxxxxxxxxxxx/artifacts/video/content \
  -H "Authorization: Bearer $COREROUTER_API_KEY" \
  --output artifact.bin

Common Issues

• model field is required: Request body or form missing model.
• prompt is required: Video tasks typically require prompt.
• seconds must be between 1 and 3600: Video duration exceeds limit or a negative number was passed.
• Submission successful but stuck queuing: Upstream task queue is busy, poll later or switch to other models.
• Cannot query task: Confirm you're using the task ID from the submission response, and API Key still has permission to access that task.
• Content download failed: Current task channel may only provide result URL, doesn't support /content proxy download.