Generate a video with TokenRoc

Before you begin

• An account and a key. Register in the console, then create a key on the API Keys page. Keep it on your server, never in browser or mobile code.
• Balance. Video is charged per generated second. Top up on the Wallet page if needed.
• A model ID. This guide uses wan3.0-video, the lowest per-second rate. Confirm it in Model Square.
• Patience. A task usually takes minutes, and sometimes much longer. Plan to check back rather than hold one connection open.

1. SubmitPOST /v1/videos
2. Save the IDid: task_...
3. CheckGET /v1/videos/{id}
4. Downloadmetadata.url

Set your key once in the terminal you will use:

export TOKENROC_API_KEY="your-api-key"

Step 1: Submit a task

Send the model, a prompt, a resolution, and a length in seconds:

curl https://api.tokenroc.com/v1/videos \
  -H "Authorization: Bearer $TOKENROC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "prompt": "A paper boat drifting across a shallow pool, soft daylight",
    "size": "480P",
    "duration": 2
  }'

Step 2: Save the task ID

TokenRoc replies straight away. The response describes the task, not the video:

{
  "id": "task_...",
  "task_id": "task_...",
  "object": "video",
  "model": "wan3.0-video",
  "status": "queued",
  "progress": 0,
  "created_at": 1790000000
}

Store id somewhere durable, such as your database, before you do anything else. It is the only way to find this video again. task_id holds the same value for older clients.

Step 3: Check the task

Ask for the task by its ID:

export TASK_ID="paste-the-id-from-step-2"

curl https://api.tokenroc.com/v1/videos/$TASK_ID \
  -H "Authorization: Bearer $TOKENROC_API_KEY"

While the video is being made, the response looks like this:

{
  "id": "task_...",
  "object": "video",
  "model": "wan3.0-video",
  "status": "in_progress",
  "progress": 30,
  "created_at": 1790000000,
  "completed_at": 1790000015,
  "metadata": { "url": "" }
}

• Check every 15 seconds or less often. TokenRoc refreshes each task from the provider about every 15 seconds, so checking faster returns the same answer.
• Decide on status only. progress moves in coarse steps, not a countdown. completed_at records the last update to the task and is set before the video is ready.
• You can only read tasks created with your own account's keys.

Step 4: Download the video

When status is completed, metadata.url contains the link. The signed link below is shortened:

{
  "id": "task_...",
  "object": "video",
  "model": "wan3.0-video",
  "status": "completed",
  "progress": 100,
  "created_at": 1790000000,
  "completed_at": 1790000300,
  "metadata": { "url": "https://<provider-storage>/<video-file>.mp4?<signature>" }
}

curl -L -o boat.mp4 "PASTE_THE_URL_FROM_metadata.url"

A complete script

This Python script submits the task, checks it every 15 seconds, and saves the MP4 when it is ready. It uses only the standard library. To keep checking a task you already submitted, pass its ID: python make_video.py task_...

import json
import os
import sys
import time
import urllib.error
import urllib.request

API = "https://api.tokenroc.com/v1"
HEADERS = {
    "Authorization": "Bearer " + os.environ["TOKENROC_API_KEY"],
    "Content-Type": "application/json",
}
WAIT_SECONDS = 30 * 60  # how long this script waits; the task keeps running after it stops


def call(method, path, body=None):
    data = None if body is None else json.dumps(body).encode()
    request = urllib.request.Request(API + path, data=data, headers=HEADERS, method=method)
    try:
        with urllib.request.urlopen(request, timeout=60) as response:
            return json.load(response)
    except urllib.error.HTTPError as err:
        sys.exit(f"HTTP {err.code}: {err.read().decode()}")


if len(sys.argv) > 1:
    task_id = sys.argv[1]
else:
    task = call("POST", "/videos", {
        "model": "wan3.0-video",
        "prompt": "A paper boat drifting across a shallow pool, soft daylight",
        "size": "480P",
        "duration": 2,
    })
    task_id = task["id"]
    print("Submitted", task_id)

deadline = time.monotonic() + WAIT_SECONDS
while True:
    task = call("GET", "/videos/" + task_id)
    status = task["status"]
    print(status, task.get("progress"))
    if status == "completed":
        urllib.request.urlretrieve(task["metadata"]["url"], task_id + ".mp4")
        print("Saved", task_id + ".mp4")
        break
    if status == "failed":
        sys.exit(f"Task failed: {task.get('error')}")
    if time.monotonic() > deadline:
        sys.exit(f"Stopped waiting while the task is {status}. "
                 f"Run this script again with {task_id} to keep checking.")
    time.sleep(15)

Stopped waiting, or failed?

These are different things, and mixing them up costs money.

A charge in your usage log does not mean the video is ready. The charge is reserved when you submit, so it appears while the task is still in_progress.

What it costs

Video is priced per generated second:

cost = seconds generated x price per second x resolution / audio factor

1. At submission, TokenRoc reserves the cost of the duration you asked for, at the resolution and audio setting you chose. If your balance cannot cover it, the task is not created.
2. When the task completes, the charge is settled against the length the provider reports it actually produced. If that differs from the reservation, the difference is refunded or charged.
3. If the task fails, the reserved amount is returned.

Worked example. The request in this guide is 2 seconds of wan3.0-video at 480P. At $0.0448 per second, that is 2 x $0.0448 = $0.0896. Our own test tasks with these settings completed on 24 September 2026 and were charged that amount. The same 2 seconds at the default 720P would be twice that.

Wan models also accept "duration": -1, which lets the provider choose the length. TokenRoc then reserves the maximum of 30 seconds and settles to the length actually generated.

Prices were checked on 24 September 2026. Model Square shows the current rate.

Choose a model

All five models use the same submit and check steps. Change model, and keep size and duration within the model's range.

Options for Kling models

• Audio: add "metadata": {"parameters": {"audio": true}}. Wan models reject audio. Turbo always has audio and rejects "audio": false. Omni cannot combine audio with a reference video.
• Aspect ratio: for a prompt-only Kling video, add "metadata": {"parameters": {"aspect_ratio": "9:16"}}. Accepted values are 16:9 (default), 9:16, and 1:1. When you supply a frame, the frame sets the shape.
• Frames: pass a public image URL in image to use it as the first frame. The standard model also accepts "images": [first, last] for first and last frames.
• Omni references: reference images and a reference video are sent as typed entries in metadata.input.media, using "type": "refer" for an image and "type": "feature" for a video.

TokenRoc checks these combinations before a task is created and rejects any it does not support, so an invalid request is never charged.

Errors

Problems found when you submit a task come back with a code and a message:

{
  "code": "invalid_request",
  "message": "duration must be between 2 and 30 seconds (got 1)",
  "data": null
}

Errors raised before a request reaches the video service, such as model_not_found, use an error object instead, like the one in the image guide. The status page shows whether the TokenRoc gateway responds. It does not report the health of each model.

Check usage

• Task Logs list every video task with its status. Use it to find a task ID you did not save.
• Usage Logs show the reservation at submission and any refund or extra charge at settlement.
• The Wallet page shows your balance.

Next steps

• Rerun the example at 720P or with a longer duration once the 2-second clip works.
• Create still images with the image generation guide.
• Read the API quickstart for text models and the endpoint list.

Stuck? Contact TokenRoc with the model ID and task ID. Never send your API key or a signed video link.