Video Generation

RouterHub provides an asynchronous video generation API. One request shape serves every supported upstream — currently Seedance (BytePlus ModelArk), MiniMax H3, and Runway (Gen 4.5 & Aleph 2.0) — selected with the model field. The workflow follows a task-based pattern: submit a generation request, then poll GET /v1/video/generations/{task_id} for results or provide a callback_url to be notified when RouterHub observes a terminal state.

Valid values for resolution, duration, ratio, and media role fields differ per model. Check MiniMax H3 Constraints and Runway Gen 4.5 & Aleph 2.0 Constraints before pointing existing code at a MiniMax or Runway model.

Overview

Available Models

Model-specific parameter constraints differ. See MiniMax H3 Constraints and Runway Gen 4.5 & Aleph 2.0 Constraints before switching a request from one model to another — resolution values, allowed ratio values, and duration rules are not interchangeable.

Task Status Lifecycle

Create Video Generation

Submit a video generation task. The response returns immediately with a task object containing a unique id for polling.

Request Body Parameters

Content Item Structure

Each element in the content array describes an input modality:

Generation Modes

These are the common Seedance request shapes supported by the API:

Parameter Constraints

The table above applies to byteplus/seedance-2.0. For minimax/minimax-h3 see the next section — its values are different and are not a superset.

MiniMax H3 Constraints

This section covers the whole MiniMax H3 family — both minimax/minimax-h3 and minimax/minimax-h3-max. They accept the same request shape as other video models, but several parameters have different valid values, and some of those values differ between the two models (see H3 vs H3 Max). Requests that violate these return 400 with an explanatory message rather than being silently adjusted.

Media limits

H3 vs H3 Max

minimax/minimax-h3-max is a speed-optimized variant of H3 (post-trained by fal.ai on MiniMax H3). It takes the same request shape — only the valid values differ, plus one response difference worth planning for.

Behaviors worth knowing

• Media order is preserved exactly as submitted. H3 prompts reference inputs positionally ("@Image 1 is the character, @Image 2 is the background"), so the gateway never reorders or drops content items. If an item is malformed, the request fails with the offending index (e.g. content[1]: url must not be empty) instead of dropping it — dropping would shift every later index and silently break your prompt references.
• Frame control and reference mode are mutually exclusive. A request may use "first_frame" / "last_frame", or the reference roles ("reference_image" / "reference_video" / "reference_audio") — never both. Mixing them returns 400: reference mode cannot be mixed with first_frame/middle_frame/last_frame; choose one.
  Note that middle_frame appears in that upstream message but is not currently usable on either model (verified 2026-09-07): minimax/minimax-h3 rejects it with role="middle_frame" invalid for type="image_url", and minimax/minimax-h3-max rejects it with model MiniMax-H3-Max does not support middle frames, use MiniMax-H3 instead — which points at a model that also rejects it. Do not build against middle_frame based on that error text alone.
• Some media problems surface only after the task is created. Parameter errors (bad role, unsupported duration) are rejected synchronously on submit. Problems that require actually reading the file — an image outside the [0.4, 2.5] aspect range, for instance — are reported asynchronously: you receive a task id with status running, and the task then moves to failed with a message such as content[3].image_url: invalid param: image aspect ratio 2.720 (=1708/628), expected in [0.4, 2.5].
  These failures are not billed — no usage is reported and the pre-authorization is released. Do not treat "task created" as "inputs accepted".
• One validation error at a time. The upstream stops at the first invalid parameter, so a request with several problems surfaces them one per attempt.
• Tasks with a reference video are pre-authorized at the 15-second maximum. The input video's real duration is not known at submit time, so the hold is calculated against the upper bound. The final charge uses the actual reported duration and the difference is released.
• No progress percentage. Status moves queued → running → succeeded / failed / cancelled with no intermediate progress value.
• Prompt quality matters more than for other models. H3 responds to structured prompts (reference-asset instructions, core concept, shot-by-shot description). Short prompts with no reference assets are a documented cause of poor results — see MiniMax's official prompting guide.

Runway Gen 4.5 & Aleph 2.0 Constraints

Runway models (runway/gen-4-5 and runway/aleph-2-0) are hosted via RunwayML. They use the standard RouterHub asynchronous task interface but follow Runway-specific input constraints and parameter bounds.

Runway Key Behaviors & Tips

• Direct Public URLs: Runway models fetch media assets directly from upstream servers. Always provide accessible public http(s):// URLs or data URIs. Platform internal asset IDs (e.g., asset_id or asset://) are rejected with 400.
• Native Output URL: Upon task completion (succeeded), the native Runway MP4 download URL is returned directly in content[0].video_url.url.
• Automatic Endpoint Selection: The gateway automatically maps your request to Runway's Text-to-Video, Image-to-Video, or Video-to-Video endpoints depending on the model and inputs provided.

Example: Text-to-Video

curl https://api.routerhub.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTERHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "byteplus/seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "A golden retriever running through a field of sunflowers at sunset, cinematic 4K, slow motion"
      }
    ],
    "duration": 10,
    "ratio": "16:9",
    "resolution": "1080p"
  }'

import requests

resp = requests.post(
    "https://api.routerhub.ai/v1/video/generations",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "byteplus/seedance-2.0",
        "content": [
            {
                "type": "text",
                "text": "A golden retriever running through a field of sunflowers at sunset, cinematic 4K, slow motion"
            }
        ],
        "duration": 10,
        "ratio": "16:9",
        "resolution": "1080p",
    },
)

task = resp.json()
print(task["id"], task["status"])
# → "cgt-20260804101917-tzl28" "queued"

Response (200 OK)

{
  "id": "cgt-20260804101917-tzl28",
  "object": "video.generation.task",
  "created": 1779767402,
  "model": "byteplus/seedance-2.0",
  "status": "queued",
  "metadata": {}
}

Example: Image-to-Video

curl https://api.routerhub.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTERHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "byteplus/seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "The character slowly turns their head and smiles at the camera"
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": {
          "url": "https://example.com/portrait.jpg"
        }
      }
    ],
    "duration": 5,
    "ratio": "9:16",
    "resolution": "1080p"
  }'

Example: With Audio and Callback

curl https://api.routerhub.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTERHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "byteplus/seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "A musician playing piano in a dimly lit jazz club"
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": {
          "url": "https://example.com/pianist-photo.jpg"
        }
      },
      {
        "type": "audio_url",
        "role": "reference_audio",
        "audio_url": {
          "url": "https://example.com/jazz-piano.mp3"
        }
      }
    ],
    "generate_audio": true,
    "duration": 15,
    "ratio": "16:9",
    "callback_url": "https://myapp.example.com/webhooks/video-done",
    "metadata": {"project": "music-video", "scene": 3}
  }'

Example: Runway Gen 4.5 (Image-to-Video)

curl https://api.routerhub.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTERHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "runway/gen-4-5",
    "content": [
      {
        "type": "text",
        "text": "Camera slowly pans up as gentle wind blows through the trees"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/forest-landscape.jpg"
        }
      }
    ],
    "duration": 5,
    "ratio": "1280:720",
    "seed": 42
  }'

Example: Runway Aleph 2.0 (Video-to-Video)

curl https://api.routerhub.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTERHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "runway/aleph-2-0",
    "content": [
      {
        "type": "text",
        "text": "Transform this video into a vibrant cyberpunk anime aesthetic with neon glow"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/street-walking.mp4"
        }
      }
    ],
    "ratio": "16:9",
    "seed": 12345
  }'

Get Video Generation

Retrieve the current status and result of a video generation task. Poll this endpoint until status reaches a terminal state (succeeded, failed, or cancelled).

Path Parameters

Example Request

curl https://api.routerhub.ai/v1/video/generations/cgt-20260804101917-tzl28 \
  -H "Authorization: Bearer $ROUTERHUB_API_KEY"

import time
import requests

task_id = "cgt-20260804101917-tzl28"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

# Polling loop
while True:
    resp = requests.get(
        f"https://api.routerhub.ai/v1/video/generations/{task_id}",
        headers=headers,
    )
    task = resp.json()
    print(f"Status: {task['status']}")

    if task["status"] in ("succeeded", "failed", "cancelled"):
        break
    time.sleep(5)  # poll every 5 seconds

# On success, content contains the video URL
if task["status"] == "succeeded":
    print("Video URL:", task["content"]["video_url"])
elif task["status"] == "failed":
    print("Failed:", task["error"])

Response: Running

{
  "id": "cgt-20260804101917-tzl28",
  "object": "video.generation.task",
  "created": 1779767402,
  "model": "byteplus/seedance-2.0",
  "status": "running",
  "updated_at": 1779767414
}

Response: Succeeded

{
  "id": "cgt-20260804101917-tzl28",
  "object": "video.generation.task",
  "created": 1779767402,
  "model": "byteplus/seedance-2.0",
  "status": "succeeded",
  "updated_at": 1779767585,
  "completed_at": 1779767585,
  "content": {
    "video_url": "https://ark-acg-ap-southeast-1.tos-ap-southeast-1.volces.com/dreamina-seedance-2-0/example.mp4?X-Tos-Algorithm=TOS4-HMAC-SHA256&..."
  },
  "usage": {
    "completion_tokens": 108900,
    "total_tokens": 108900
  },
  "resolution": "720p",
  "duration": 5,
  "seed": 8598,
  "metadata": {}
}

Response: Failed

{
  "id": "cgt-20260804101917-tzl28",
  "object": "video.generation.task",
  "created": 1779767402,
  "model": "byteplus/seedance-2.0",
  "status": "failed",
  "updated_at": 1779767445,
  "completed_at": 1779767445,
  "error": {
    "code": "content_policy_violation",
    "message": "The prompt was rejected due to content policy.",
    "type": "video_generation_error",
    "param": null
  }
}

List Video Generations

List all non-deleted video generation tasks for the authenticated API key. Results are ordered by created_at DESC, task_id DESC and support cursor-based pagination.

Query Parameters

Example Request

curl "https://api.routerhub.ai/v1/video/generations?limit=5" \
  -H "Authorization: Bearer $ROUTERHUB_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "cgt-20260804101917-tzl28",
      "object": "video.generation.task",
      "created": 1779767402,
      "model": "byteplus/seedance-2.0",
      "status": "succeeded",
      "completed_at": 1779767585
    },
    {
      "id": "cgt-20260804101349-cd74q",
      "object": "video.generation.task",
      "created": 1779767229,
      "model": "byteplus/seedance-2.0",
      "status": "running"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJjIjoiMjAyNi0wOC0wNFQxMDowMzo0OVoiLCJ0IjoiY2d0LTIwMjYwODA0MTAxMzQ5LWNkNzRxIn0"
}

Delete Video Generation

Delete a video generation task. The task is cancelled and removed from your task list.

Path Parameters

Example Request

curl -X DELETE https://api.routerhub.ai/v1/video/generations/cgt-20260804101917-tzl28 \
  -H "Authorization: Bearer $ROUTERHUB_API_KEY"

Response (200 OK)

{
  "id": "cgt-20260804101917-tzl28",
  "object": "video.generation.task",
  "deleted": true
}

Webhook Callback

If you provide a callback_url in the Create request, RouterHub will POST the task JSON to that URL when the task reaches a terminal state (succeeded, failed, or cancelled).

Registration

To register a webhook, simply include callback_url in your Create request body:

curl https://api.routerhub.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTERHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "byteplus/seedance-2.0",
    "content": [
      {"type": "text", "text": "A cat playing with a ball of yarn"}
    ],
    "duration": 5,
    "ratio": "16:9",
    "callback_url": "https://myapp.example.com/webhooks/video-done"
  }'

Callback Payload

When the task reaches a terminal state, RouterHub sends an HTTP POST to your callback_url with the following characteristics:

Callback Request Example

Here is what RouterHub sends to your server when a task succeeds:

POST /webhooks/video-done HTTP/1.1
Host: myapp.example.com
Content-Type: application/json

{
  "id": "cgt-20260804101917-tzl28",
  "object": "video.generation.task",
  "created": 1779767402,
  "model": "byteplus/seedance-2.0",
  "status": "succeeded",
  "completed_at": 1779767585,
  "content": {
    "video_url": "https://ark-acg-ap-southeast-1.tos-ap-southeast-1.volces.com/dreamina-seedance-2-0/example.mp4?X-Tos-Algorithm=TOS4-HMAC-SHA256&..."
  },
  "resolution": "720p",
  "duration": 5,
  "seed": 8598,
  "metadata": {"project": "music-video", "scene": 3}
}

And when a task fails:

POST /webhooks/video-done HTTP/1.1
Host: myapp.example.com
Content-Type: application/json

{
  "id": "cgt-20260804101917-tzl28",
  "object": "video.generation.task",
  "created": 1779767402,
  "model": "byteplus/seedance-2.0",
  "status": "failed",
  "completed_at": 1779767445,
  "error": {
    "code": "content_policy_violation",
    "message": "The prompt was rejected due to content policy.",
    "type": "video_generation_error",
    "param": null
  },
  "metadata": {}
}

Callback Response

Your server should respond with HTTP 200 to acknowledge receipt. RouterHub treats the following response codes as follows:

Retry Policy

RouterHub retries failed deliveries (5xx or network errors) up to 3 total attempts with exponential backoff:

Webhook Handler Example

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.post("/webhooks/video-done")
def handle_video_callback():
    task = request.get_json()
    task_id = task["id"]
    status = task["status"]

    if status == "succeeded":
        video_url = task["content"]["video_url"]
        print(f"Task {task_id} succeeded: {video_url}")
        # Download the video (URL is time-limited, typically 24h)
        # ...
    elif status == "failed":
        error = task.get("error", {})
        print(f"Task {task_id} failed: {error.get('message')}")
    elif status == "cancelled":
        print(f"Task {task_id} was cancelled")

    # Respond 200 to acknowledge receipt
    return jsonify({"ok": True}), 200

const express = require("express");
const app = express();

app.use(express.json());

app.post("/webhooks/video-done", (req, res) => {
  const task = req.body;
  const { id, status } = task;

  if (status === "succeeded") {
    const videoUrl = task.content.video_url;
    console.log(`Task ${id} succeeded: ${videoUrl}`);
    // Download the video (URL is time-limited, typically 24h)
  } else if (status === "failed") {
    const error = task.error || {};
    console.log(`Task ${id} failed: ${error.message}`);
  } else if (status === "cancelled") {
    console.log(`Task ${id} was cancelled`);
  }

  // Respond 200 to acknowledge receipt
  res.json({ ok: true });
});

app.listen(3000);

Complete Workflow Example

Here's a full Python example that creates a video, polls for completion, and downloads the result:

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.routerhub.ai"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# Step 1: Create the video generation task
create_resp = requests.post(
    f"{BASE_URL}/v1/video/generations",
    headers=headers,
    json={
        "model": "byteplus/seedance-2.0",
        "content": [
            {"type": "text", "text": "A serene ocean wave crashing on a rocky shore at golden hour, 4K cinematic"},
            {
                "type": "image_url",
                "role": "reference_image",
                "image_url": {"url": "https://example.com/beach-reference.jpg"},
            },
        ],
        "duration": 10,
        "ratio": "16:9",
        "resolution": "1080p",
        "generate_audio": True,
    },
)
create_resp.raise_for_status()
task = create_resp.json()
task_id = task["id"]
print(f"Task created: {task_id} (status: {task['status']})")

# Step 2: Poll until terminal state
while task["status"] not in ("succeeded", "failed", "cancelled"):
    time.sleep(5)
    poll_resp = requests.get(f"{BASE_URL}/v1/video/generations/{task_id}", headers=headers)
    poll_resp.raise_for_status()
    task = poll_resp.json()
    print(f"  Status: {task['status']}")

# Step 3: Handle result
if task["status"] == "succeeded":
    video_url = task["content"]["video_url"]
    print(f"Video URL: {video_url}")

    # Download the video (URL is time-limited, typically 24h)
    video_data = requests.get(video_url).content
    with open("output.mp4", "wb") as f:
        f.write(video_data)
    print("Saved to output.mp4")

elif task["status"] == "failed":
    print(f"Generation failed: {task['error']['message']}")

elif task["status"] == "cancelled":
    print("Task was cancelled")

Error Responses

Error responses use the same top-level OpenAI-style error envelope as the rest of RouterHub. The exact type string varies by code path, so the table below focuses on status and trigger conditions that are confirmed in the implementation.

{
  "error": {
    "message": "content must contain at least one item",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

Video Assets

The Video Assets API allows you to upload media files (images, videos, audio) to the asset library for use as references in video generation. Assets are uploaded via URL, processed and moderated by upstream, then become available for use in generation requests. Each organization has an asset group; assets are organized within that group.

Asset Status Lifecycle

Create Asset

Upload a media file by providing its HTTPS URL. The asset will be processed and moderated by the upstream service. The response returns immediately with the asset ID and a processing status.

Request Body Parameters

Example Request

curl https://api.routerhub.ai/v1/video/assets \
  -H "Authorization: Bearer $ROUTERHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/my-reference-image.jpg",
    "asset_type": "Image",
    "name": "Beach portrait reference"
  }'

import requests

resp = requests.post(
    "https://api.routerhub.ai/v1/video/assets",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://example.com/my-reference-image.jpg",
        "asset_type": "Image",
        "name": "Beach portrait reference",
    },
)

asset = resp.json()
print(asset["id"], asset["status"])
# → "asset-20260804100000-abc12" "processing"

Response (200 OK)

{
  "id": "asset-20260804100000-abc12",
  "object": "video.asset",
  "status": "processing"
}

Get Asset

Retrieve the current status and details of an asset. Poll this endpoint to check when an asset becomes active and ready for use in video generation requests.

Path Parameters

Example Request

curl https://api.routerhub.ai/v1/video/assets/asset-20260804100000-abc12 \
  -H "Authorization: Bearer $ROUTERHUB_API_KEY"

Response: Processing

{
  "id": "asset-20260804100000-abc12",
  "object": "video.asset",
  "name": "Beach portrait reference",
  "asset_type": "Image",
  "status": "processing",
  "created_at": "2026-08-04T10:00:00Z",
  "updated_at": "2026-08-04T10:00:00Z"
}

Response: Active

{
  "id": "asset-20260804100000-abc12",
  "object": "video.asset",
  "name": "Beach portrait reference",
  "url": "https://cdn.example.com/assets/processed_abc12.jpg",
  "asset_type": "Image",
  "group_id": "grp-20260804100000-xyz",
  "status": "active",
  "created_at": "2026-08-04T10:00:00Z",
  "updated_at": "2026-08-04T10:00:15Z"
}

Response: Failed

{
  "id": "asset-20260804100000-abc12",
  "object": "video.asset",
  "name": "Beach portrait reference",
  "asset_type": "Image",
  "status": "failed",
  "error": {
    "code": "moderation_rejected",
    "message": "Asset rejected during content moderation"
  },
  "created_at": "2026-08-04T10:00:00Z",
  "updated_at": "2026-08-04T10:00:20Z"
}

List Assets

List assets in your organization's asset library. Supports page-based pagination and optional filtering by group_id.

Query Parameters

Example Request

curl "https://api.routerhub.ai/v1/video/assets?page=1&limit=10" \
  -H "Authorization: Bearer $ROUTERHUB_API_KEY"

Response

{
  "object": "list",
  "items": [
    {
      "id": "asset-20260804100000-abc12",
      "name": "Beach portrait reference",
      "url": "https://cdn.example.com/assets/processed_abc12.jpg",
      "asset_type": "Image",
      "group_id": "grp-20260804100000-xyz",
      "status": "active",
      "created_at": "2026-08-04T10:00:00Z",
      "updated_at": "2026-08-04T10:00:15Z"
    }
  ],
  "total_count": 1,
  "page_number": 1,
  "page_size": 10
}

Asset Error Responses

Using Assets in Video Generation

Once an asset reaches active status, use the asset://{asset_id} protocol URL (or the asset_id field) in your video generation request's media fields. The gateway resolves the asset reference automatically:

# Step 1: Create an image asset
curl https://api.routerhub.ai/v1/video/assets \
  -H "Authorization: Bearer $ROUTERHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/my-portrait.jpg",
    "asset_type": "Image",
    "name": "Portrait reference"
  }'
# → {"id":"asset-20260804100000-abc12","object":"video.asset","status":"processing"}

# Step 2: Poll until active
curl https://api.routerhub.ai/v1/video/assets/asset-20260804100000-abc12 \
  -H "Authorization: Bearer $ROUTERHUB_API_KEY"
# → {"id":"asset-20260804100000-abc12","object":"video.asset","status":"active",...}

# Step 3: Use asset:// protocol URL in video generation
curl https://api.routerhub.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTERHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "byteplus/seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "The person slowly turns their head and smiles warmly at the camera"
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": {
          "url": "asset://asset-20260804100000-abc12"
        }
      }
    ],
    "duration": 5,
    "ratio": "9:16"
  }'

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.routerhub.ai"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# Step 1: Upload an image asset
asset_resp = requests.post(
    f"{BASE_URL}/v1/video/assets",
    headers=headers,
    json={
        "url": "https://example.com/my-portrait.jpg",
        "asset_type": "Image",
        "name": "Portrait reference",
    },
)
asset_resp.raise_for_status()
asset_id = asset_resp.json()["id"]
print(f"Asset created: {asset_id}")

# Step 2: Poll until the asset is active
while True:
    get_resp = requests.get(f"{BASE_URL}/v1/video/assets/{asset_id}", headers=headers)
    get_resp.raise_for_status()
    asset = get_resp.json()
    print(f"  Asset status: {asset['status']}")
    if asset["status"] == "active":
        break
    elif asset["status"] == "failed":
        raise RuntimeError(f"Asset failed: {asset.get('error', {}).get('message')}")
    time.sleep(3)

print(f"Asset ready: {asset_id}")

# Step 3: Use asset:// protocol URL in video generation
gen_resp = requests.post(
    f"{BASE_URL}/v1/video/generations",
    headers=headers,
    json={
        "model": "byteplus/seedance-2.0",
        "content": [
            {
                "type": "text",
                "text": "The person slowly turns their head and smiles warmly at the camera",
            },
            {
                "type": "image_url",
                "role": "reference_image",
                "image_url": {"url": f"asset://{asset_id}"},
            },
        ],
        "duration": 5,
        "ratio": "9:16",
    },
)
gen_resp.raise_for_status()
task = gen_resp.json()
print(f"Video task created: {task['id']} (status: {task['status']})")

# Step 4: Poll video generation until complete
while task["status"] not in ("succeeded", "failed", "cancelled"):
    time.sleep(5)
    poll_resp = requests.get(f"{BASE_URL}/v1/video/generations/{task['id']}", headers=headers)
    poll_resp.raise_for_status()
    task = poll_resp.json()
    print(f"  Video status: {task['status']}")

if task["status"] == "succeeded":
    print("Video URL:", task["content"]["video_url"])

Real-Human Asset Sessions

Some video generation use cases require a verified real-human asset (e.g. a consented portrait for likeness generation). RouterHub exposes a session-based H5 flow: you create a session, receive an H5 link, the subject completes verification on their device, and RouterHub redirects them back to your callback_url with the outcome.

Create Session

Create a real-human verification session. The response returns an h5_link that you should open on the subject's device. After the subject completes (or abandons) the flow, BytePlus redirects to the platform callback at /v1/video/assets/sessions/callback, which in turn redirects to your callback_url.

Request Body Parameters

Example Request

curl https://api.routerhub.ai/v1/video/assets/sessions \
  -H "Authorization: Bearer $ROUTERHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://myapp.example.com/webhooks/real-human-done",
    "lang": "en"
  }'

Response (200 OK)

{
  "object": "video.asset_session",
  "status": "pending",
  "h5_link": "https://visual-validate.byteplusapi.com/h5/verify?token=...",
  "expires_at": "2026-08-04T11:00:00Z"
}

Session Status Lifecycle

Platform Callback (Inbound)

This endpoint is the platform inbound callback that BytePlus redirects the subject's browser to after the H5 flow. It is not intended for direct client use. RouterHub updates the session status and then redirects the subject's browser (HTTP 302) to your callback_url with forwarded query parameters (e.g. group_id, result, code).

Rate Limits & Billing

• Rate limits are enforced during create.
• Prepaid credit is reserved during create and settled when the task completes.
• Timeouts: if a task does not complete within its effective timeout (default 2 hours, overridable via execution_expires_after), it is marked failed with error.code = "video_timeout".