API Reference

Video Generation

POSThttps://api.tokenbay.com/v1/videos

Asynchronous video generation: submit a task, poll its status, then download the result

One OpenAI-style entry point serves multiple video model families (HappyHorse, Veo 3.1, Seedance). The model field in the request body selects the target model; the rest of the body is model-specific.

Success and business failures both return HTTP 200. A successful response carries the task fields at the top level of the JSON body (no data wrapper); a failed call carries an error object ({ message, type, code }) instead.

Video routes disable failover retries by default because task creation is not idempotent.

Submit a Generation Task

openaiFailover: disabled

Authenticates the Authorization header, then routes by the model field in the request body to the matching model.

Task creation is not idempotent, so failover retries are disabled for video routes.

POST/v1/videosCompatibility aliasPOST/v1/video/generations

Request

schema

Common top-level fields. The exact field set is defined per model family — see the HappyHorse, Veo 3.1, and Seedance pages.

modelstringRequired

Video model ID. Selects the target model and task type. Documented families: HappyHorse, Veo 3.1, Seedance — see the model pages for their full parameter sets.

promptstringRequired

Video description prompt. Length limits and language guidance vary by model.

image / images / input_reference / last_frame_image / reference_imagesstring | array<string>Optional

Image inputs for image-to-video, first/last-frame, and reference workflows. Field names and limits vary by model — see the model pages.

duration / secondsinteger | stringOptional

Video duration in seconds. Supported tiers and defaults vary by model.

resolution / sizestringOptional

Resolution tier, such as 720p or 1080p. Supported values vary by model.

aspect_ratiostringOptional

Aspect ratio such as 16:9 or 9:16. HappyHorse and Seedance take ratio inside metadata instead.

negative_promptstringOptional

Negative prompt. Support depends on the model.

seedintegerOptional

Random seed for best-effort reproducibility.

generate_audiobooleanOptional

Whether to generate audio; only applies to models that support it.

metadataobjectOptional

Vendor-specific parameter container. The accepted keys are defined per model family — see the model pages.

Response

schema

Submission receipt, returned at the top level of the JSON body.

idstringOptional

Task ID (task_xxx). Same value as task_id, kept for OpenAI SDK compatibility.

task_idstringOptional

Task ID used for polling and download.

objectstringOptional

Always video.

modelstringOptional

Model name from the request.

statusstringOptional

Initial task status, usually QUEUED.

SUBMITTEDQUEUEDIN_PROGRESSSUCCESSFAILURE

progressintegerOptional

Progress 0–100, usually 0 right after submission.

created_atintegerOptional

Task creation time (Unix seconds).

Authentication uses the Authorization: Bearer sk-xxx header only; never put the API key in the request body.

Check for the error field in the body to tell success from failure — the HTTP status is 200 either way.

Query Task Detail

GET/v1/videos/{task_id}Compatibility aliasGET/v1/video/generations/{task_id}

Response

schema

Task detail, returned at the top level of the JSON body.

task_idstringOptional

Task ID.

actionstringOptional

Task action, such as generate.

statusstringOptional

Task status. SUCCESS and FAILURE are terminal.

SUBMITTEDQUEUEDIN_PROGRESSSUCCESSFAILURE

progressstringOptional

Progress percentage string, such as "50%".

result_urlstringOptional

Result video download URL, present when status is SUCCESS. Has the form /v1/videos/{task_id}/content.

fail_reasonstringOptional

Failure reason, present when status is FAILURE.

quotaintegerOptional

Quota consumed by this task, filled after settlement.

submit_time / start_time / finish_timeintegerOptional

Task submission, execution start, and completion times (Unix seconds).

created_at / updated_atintegerOptional

Record creation and last update times (Unix seconds).

errorobjectOptional

Task-level error detail, present for failed tasks.

error.messagestringOptional

Error message.

error.codestringOptional

Error code.

Status lifecycle: SUBMITTED → QUEUED → IN_PROGRESS → SUCCESS / FAILURE. SUCCESS and FAILURE are terminal.

Poll every 10–15 seconds and never below 5 seconds. Suggested overall timeout: 5 minutes for generation tasks, 8–10 minutes for video editing.

On FAILURE, read fail_reason (and the error object when present) for the cause.

Download the Result

GET/v1/videos/{task_id}/content

Response

binary

video/mp4 byte stream.

The result_url returned by the query endpoint is exactly this URL — use either interchangeably.

Range requests are supported (HTTP 206) for resumable downloads and seek-while-playing in video players.

Submit a Generation Task

bashSubmit a task

Language

curl -X POST https://api.tokenbay.com/v1/videos \
  -H "Authorization: Bearer sk-XXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0-t2v",
    "prompt": "A cat dozing in the sunshine, fur swaying gently in the breeze",
    "size": "720P",
    "duration": 5
  }'

200 json200 response

Language

{
  "id": "task_9dXfUz8h5GxBvDqIvYoVnZ3r",
  "task_id": "task_9dXfUz8h5GxBvDqIvYoVnZ3r",
  "object": "video",
  "model": "happyhorse-1.0-t2v",
  "status": "QUEUED",
  "progress": 0,
  "created_at": 1778250615
}

bashBusiness failure shape (also HTTP 200)

Language

curl -X POST https://api.tokenbay.com/v1/videos \
  -H "Authorization: Bearer sk-XXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "model": "not-a-video-model", "prompt": "..." }'

200 json200 response

Language

{
  "error": {
    "message": "Unsupported video model: not-a-video-model",
    "type": "invalid_request_error",
    "code": "invalid_model"
  }
}

Query Task Detail

bashPoll the task

Language

curl https://api.tokenbay.com/v1/videos/task_9dXfUz8h5GxBvDqIvYoVnZ3r \
  -H "Authorization: Bearer sk-XXXXXXX"

200 json200 response

Language

{
  "task_id": "task_9dXfUz8h5GxBvDqIvYoVnZ3r",
  "action": "generate",
  "status": "SUCCESS",
  "progress": "100%",
  "result_url": "https://api.tokenbay.com/v1/videos/task_9dXfUz8h5GxBvDqIvYoVnZ3r/content",
  "quota": 12000,
  "submit_time": 1778250615,
  "start_time": 1778250620,
  "finish_time": 1778250745,
  "created_at": 1778250615,
  "updated_at": 1778250745
}

Download the Result

bashDownload the result

Language

curl -L https://api.tokenbay.com/v1/videos/task_9dXfUz8h5GxBvDqIvYoVnZ3r/content \
  -H "Authorization: Bearer sk-XXXXXXX" \
  -o result.mp4

bashResume an interrupted download (Range)

Language

curl https://api.tokenbay.com/v1/videos/task_9dXfUz8h5GxBvDqIvYoVnZ3r/content \
  -H "Authorization: Bearer sk-XXXXXXX" \
  -H "Range: bytes=1048576-" \
  -o result.part.mp4

Submit a Generation Task

Request

Response

Query Task Detail

Response

Download the Result

Response

Related