Video Generation

Generate a video from text, an image, or a reference video. Video generation is asynchronous: create a job, poll its status, and fetch the video URL when it completes.

Endpoints

Create a job:

POST https://gateway.mytokengate.com/v1/videos

Query a job:

GET https://gateway.mytokengate.com/v1/videos/{task_id}

Authentication

Every request must include a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Supported Models

Four model families are available. The protocol is uniform: switching models only changes the model field. Assets go in content, parameters go in parameters, and everything else stays the same.

For Kling, the standard tier renders 720p and the pro tier renders 1080p — the tier decides the resolution. Requesting 1080p from a model that does not support it fails, and the pre-authorized amount is released automatically.

Full request examples per family are in Request Examples by Family.

Create a Job

Request example

curl --request POST \
  --url https://gateway.mytokengate.com/v1/videos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2.0",
    "prompt": "A hummingbird hovering near a red flower, ultra slow motion, macro",
    "parameters": {
      "duration": 5,
      "resolution": "1080p",
      "ratio": "16:9"
    }
  }'

Request parameters

* Provide at least one of prompt or content.

parameters keys:

Response

{
  "id": "b1f9c3a2e4d7",
  "object": "video",
  "created_at": 1753420000,
  "status": "processing",
  "model": "seedance-2.0"
}

The returned id is a gateway-generated task ID (opaque string); pass it back as-is to query the job status.

Query a Job

Poll the job status with the id from the create response. Poll about every 5 seconds; a job that does not finish within 15 minutes is marked failed and the pre-authorization is released.

Request example

curl --request GET \
  --url 'https://gateway.mytokengate.com/v1/videos/b1f9c3a2e4d7' \
  --header 'Authorization: Bearer <token>'

Response (processing)

{
  "id": "b1f9c3a2e4d7",
  "object": "video",
  "status": "processing",
  "model": "seedance-2.0"
}

Response (completed)

{
  "id": "b1f9c3a2e4d7",
  "object": "video",
  "status": "completed",
  "model": "seedance-2.0",
  "output": {
    "video_url": "https://.../video.mp4"
  },
  "usage": {
    "completionTokens": 245025,
    "totalTokens": 245025
  }
}

Response fields

The download URL returned after generation is a MyTokenGate address. It is retained for about 7 days, so download and keep your video soon after generation; after it expires you will need to generate again.

Image-to-Video

Image-to-video uses a content array in place of prompt, containing a text block and an image block. The image is provided via a public HTTPS URL, and role sets its purpose (for example first_frame, reference_image).

{
  "model": "seedance-2.0",
  "content": [
    { "type": "text", "text": "The camera slowly zooms in, petals drifting in the wind" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first-frame.jpg" },
      "role": "first_frame"
    }
  ],
  "parameters": {
    "duration": 5,
    "resolution": "720p"
  }
}

The output resolution matches the image aspect ratio; use a 16:9, 9:16, or 1:1 image.

Video-to-Video

Video-to-video adds a reference video on top of the text prompt; the model reinterprets or restyles it while preserving the original motion and timing. The reference video is provided via a public HTTPS URL, with role set to reference_video.

{
  "model": "seedance-2.0",
  "content": [
    { "type": "text", "text": "Restyle into a dreamy watercolor animation, keep the motion and timing" },
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/reference.mp4" },
      "role": "reference_video"
    }
  ],
  "parameters": {
    "duration": 5,
    "resolution": "720p"
  }
}

The reference video must be a publicly downloadable common format (such as MP4), ideally close in length to the target output. Because it includes a video input, video-to-video usually consumes more tokens than text-to-video at the same resolution. Supported on seedance-2.0, kling-o3-standard-v2v, and kling-o3-pro-v2v.

Video Edit / Source-Video Rewrite (video-edit / v2v)

Some models (happyhorse-1.0-video-edit, kling-o3-standard-video-edit, kling-o3-pro-video-edit) take a source video as input and rewrite or reinterpret it. Provide the source video as a single video_url block inside content, with role set to reference_video — the same way you supply any other video input.

You do not choose an upstream field. The gateway hides the source-asset field differences between target models and routes the video to the correct upstream field automatically.

{
  "model": "happyhorse-1.0-video-edit",
  "content": [
    { "type": "text", "text": "Restyle into a dreamy watercolor animation, keep the motion" },
    { "type": "video_url", "video_url": { "url": "https://example.com/source.mp4" }, "role": "reference_video" }
  ],
  "parameters": { "resolution": "720p" }
}

The create/poll flow and response shape match the other video tasks. Source-video rewrite includes a video input, so token usage is typically about twice that of pure generation at the same resolution; settle by the task’s final usage.completionTokens.

Request Examples by Family

Below is one representative request body per family. Within a family, switching models only means replacing model — the structure does not change. Across families it is the same contract too; the only differences are which modes and resolutions a model supports.

Seedance 2.0 — text-to-video

{
  "model": "seedance-2.0",
  "prompt": "Aerial shot of ocean waves crashing on a rocky shore at sunset, cinematic",
  "parameters": {
    "duration": 5,
    "resolution": "1080p",
    "ratio": "16:9"
  }
}

seedance-2.0 also handles image-to-video and video-to-video — replace prompt with a content array containing an image or video block. seedance-2.0-fast and seedance-2.0-mini render 720p only, so set resolution to 720p.

Wan 2.7 — image-to-video

{
  "model": "wan-2-7-i2v",
  "content": [
    { "type": "text", "text": "Slow cinematic camera push, natural subject motion, preserve composition, no text, no logo" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first-frame.jpg" },
      "role": "first_frame"
    }
  ],
  "parameters": {
    "duration": 5,
    "resolution": "1080p",
    "ratio": "16:9"
  }
}

For text-to-video use wan-2-7-t2v: drop the image block and keep only the text block, or use the top-level prompt.

HappyHorse 1.1 — reference-to-video

Reference-to-video gives the model several images so the subject and style stay consistent throughout the clip. The first image must use role: "first_frame"; the rest use reference_image.

{
  "model": "happyhorse-1.1-r2v",
  "content": [
    { "type": "text", "text": "Keep the subject and style consistent across the scene, smooth motion, cinematic, no text" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first-frame.jpg" },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/reference-1.jpg" },
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/reference-2.jpg" },
      "role": "reference_image"
    }
  ],
  "parameters": {
    "duration": 5,
    "resolution": "1080p",
    "ratio": "16:9"
  }
}

role accepts only first_frame, reference_image, reference_video, reference_audio, and last_frame. Any other value is rejected upstream, usually with an error about a missing prompt or first-frame image.

In the same family, happyhorse-1.1-t2v and happyhorse-1.1-i2v cover text-to-video and image-to-video, and happyhorse-1.0-video-edit covers video editing — see the “Video Edit / Source-Video Rewrite” section above.

Kling O3 — video-to-video

{
  "model": "kling-o3-standard-v2v",
  "content": [
    { "type": "text", "text": "Restyle into a dreamy watercolor animation, keep motion and timing, no text, no logo" },
    {
      "type": "video_url",
      "video_url": { "url": "https://example.com/source.mp4" },
      "role": "reference_video"
    }
  ],
  "parameters": {
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9"
  }
}

Switch to kling-o3-pro-v2v for 1080p. Video editing uses kling-o3-standard-video-edit or kling-o3-pro-video-edit with the same body structure. Text-to-video uses kling-o3-standard, image-to-video uses kling-o3-pro-i2v, and reference-to-video uses kling-o3-standard-reference.

Full Example (Python)

import time
import requests
 
BASE_URL = "https://gateway.mytokengate.com/v1"
API_KEY = "YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
 
# 1. Create the job
create = requests.post(
    f"{BASE_URL}/videos",
    headers=HEADERS,
    json={
        "model": "seedance-2.0",
        "prompt": "Aerial shot of ocean waves crashing on a rocky shore at sunset",
        "parameters": {
            "duration": 5,
            "resolution": "1080p",
            "ratio": "16:9",
        },
    },
).json()
task_id = create["id"]
print("task:", task_id)
 
# 2. Poll for the result
while True:
    status = requests.get(
        f"{BASE_URL}/videos/{task_id}",
        headers=HEADERS,
    ).json()
    if status["status"] == "completed":
        print("video:", status["output"]["video_url"])
        break
    if status["status"] == "failed":
        print("failed:", status.get("error"))
        break
    time.sleep(5)

Billing

Video is billed by output tokens and settled at the actual usage.completionTokens when the job completes. Token usage varies with resolution, duration, and input type (1080p and reference-video inputs use more), and 1080p also has a higher unit price. Insufficient balance is rejected before generation; on failure the pre-authorized amount is released with no charge. See Billing for per-model prices.

Error Codes