Videos API

Updated: 2026-07-27

The Videos API is an asynchronous video-generation interface. When a task finishes, the generated video is served from your CDN / R2 location; upstream video URLs are not returned.

Overview

The complete integration has three steps:

POST /v1/videos to create a video-generation task
GET /v1/videos/{id} to poll the task status
GET /v1/videos/{id}/content to retrieve the generated video

Base URL: https://api.routin.ai

The recommended request format is multimodal content[]. It supports a single image, up to nine reference images, and mixed text-and-image input.

Authentication

Every request must include an API key:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Format

Recommended: `content[]` multimodal format

Use this format for a single reference image, up to nine reference images, or mixed text-and-image input.

{
  "model": "YOUR_MODEL",
  "prompt": "They are fighting",
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720p",
  "generate_audio": true,
  "content": [
    {
      "type": "text",
      "text": "They are fighting in a live-action action-film style, with fast exchanges, natural camera movement, and sharp imagery."
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://example.com/ref-1.jpg"
      }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://example.com/ref-2.jpg"
      }
    }
  ]
}

Each reference image uses the following structure. content[] supports up to nine reference images:

{
  "type": "image_url",
  "role": "reference_image",
  "image_url": {
    "url": "https://example.com/ref-9.jpg"
  }
}

Reference images can be publicly accessible URLs or data:image/jpeg;base64,... values. We recommend that images meet these requirements:

Both width and height are between 300 and 6000 pixels.
The aspect ratio is between 0.4 and 2.5.
Each image is no larger than 30MB.

Compatible single-image format

For a single reference image, you can also use this compatible flat format:

{
  "model": "YOUR_MODEL",
  "prompt": "They are fighting",
  "size": "1280x720",
  "seconds": "5",
  "input_reference": "https://example.com/ref.jpg"
}

Create a Task

Submit a generation task with POST /v1/videos. This example supplies nine reference images:

curl https://api.routin.ai/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "prompt": "They are fighting",
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true,
    "content": [
      {
        "type": "text",
        "text": "They are fighting in a live-action action-film style, with fast exchanges, natural camera movement, and sharp imagery."
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://example.com/ref-1.jpg" }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://example.com/ref-2.jpg" }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://example.com/ref-3.jpg" }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://example.com/ref-4.jpg" }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://example.com/ref-5.jpg" }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://example.com/ref-6.jpg" }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://example.com/ref-7.jpg" }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://example.com/ref-8.jpg" }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://example.com/ref-9.jpg" }
      }
    ]
  }'

Create Response

{
  "id": "task_xxxxxxxx",
  "task_id": "task_xxxxxxxx",
  "object": "video",
  "model": "YOUR_MODEL",
  "status": "queued",
  "progress": 0,
  "created_at": 1785083345,
  "seconds": 5
}

Retrieve a Task

Use GET /v1/videos/{id} to retrieve the task status:

curl https://api.routin.ai/v1/videos/task_xxxxxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

Status Values

queued: Waiting for processing
in_progress: Generating
completed: Generation completed
failed: Generation failed
cancelled: Task was cancelled

Completed Response

{
  "id": "task_xxxxxxxx",
  "object": "video",
  "model": "YOUR_MODEL",
  "status": "completed",
  "progress": 100,
  "seconds": 5,
  "usage": {
    "seconds": 5,
    "video_count": 1
  },
  "video_url": "https://api.routin.ai/video-jobs/.../content.mp4",
  "metadata": {
    "url": "https://api.routin.ai/video-jobs/.../content.mp4",
    "r2_url": "https://api.routin.ai/video-jobs/.../content.mp4",
    "r2_key": "video-jobs/.../content.mp4"
  }
}

Retrieve the Video

After the task completes, call GET /v1/videos/{id}/content to download the video:

curl -L https://api.routin.ai/v1/videos/task_xxxxxxxx/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o out.mp4

The endpoint returns 302. Its Location header points to your CDN / R2 video location and does not expose the upstream video URL to end users.

Integration Recommendations

Use content[] for multiple reference images.
Use 5s duration consistently.
Ensure resolution is supported by the selected model.
Poll task status every 3 to 5 seconds.
Retry a failed task only once; if it fails again, return a failure response to the caller.

Verified Results

The tests used real-person reference images and a 5s duration. Every task was generated successfully. The /content endpoint ultimately returned a 302 redirect to cdn.guoguomg.com.

Error Handling

Common failure causes include:

Reference images are too small.
A reference-image URL cannot be accessed or does not resolve to an image.
The image format is unsupported.
The model name and resolution do not match.

Return a short, stable error structure to callers:

{
  "error": {
    "message": "generation failed",
    "type": "server_error"
  }
}

Videos API

On this page