API Reference

HappyHorse

HappyHorse 1.0 text-to-video, image-to-video, and reference-to-video

HappyHorse 1.0 covers three task types behind one endpoint: text-to-video (t2v), image-to-video (i2v), and reference-to-video (r2v). The model field selects the task type.

All tasks are asynchronous: submit, poll the task status, then download the result. The full lifecycle is documented on the Video Generation page.

Model Lineup

happyhorse-1.0-t2v — text to video. Aspect ratios 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 4:5 / 5:4 / 9:21 / 21:9; duration 3–15 s.

happyhorse-1.0-i2v — image to video from one first-frame image (input_reference). Aspect ratio follows the input image; duration 3–15 s.

happyhorse-1.0-r2v — reference to video from 1–9 reference images. Aspect ratios 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 4:5 / 5:4 / 9:21 / 21:9; duration 3–15 s.

Submit a Generation Task

openaiFailover: disabled

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

JSON body. Field support varies by task type — see each field description.

modelstringRequired

HappyHorse model name; selects the task type.

happyhorse-1.0-t2vhappyhorse-1.0-i2vhappyhorse-1.0-r2v

promptstringOptional

Text prompt, up to 5000 non-Chinese or 2500 Chinese characters. Required for t2v and r2v; optional for i2v. For r2v you can reference inputs positionally, e.g. "[Image 1]", "[Image 2]".

sizestringOptional

Resolution tier. Defaults to 1080P.

720P1080P

durationintegerOptional

Video duration in seconds, 3–15. Defaults to 5.

input_referencestringOptional

i2v first-frame image URL (exactly one). May also be passed via metadata.input.media.

metadataobjectOptional

HappyHorse-specific parameter container.

metadata.ratiostringOptional

Aspect ratio for t2v and r2v. Defaults to 16:9. i2v ignores this — output ratio follows the first-frame image.

16:99:161:14:33:44:55:49:2121:9

metadata.watermarkbooleanOptional

Whether to add a watermark. Defaults to true.

metadata.seedintegerOptional

Random seed, 0–2147483647.

metadata.reference_typestringOptional

r2v only: how reference images are used — subject (the subject/person) or style (the visual style).

subjectstyle

metadata.input.media[]array<object>Optional

Reference media for r2v: 1–9 items. For i2v, a single first-frame image can be passed here instead of input_reference.

media[].typestringOptional

Media role.

reference_imagevideofirst_frame

media[].urlstringOptional

Media file URL.

Response

schema

Submission receipt. Fields are returned at the top level of the JSON body (no data wrapper).

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).

Image inputs (i2v first frame, r2v references): JPEG / JPG / PNG / WEBP, both sides ≥ 300 px (720P or higher recommended for r2v), file size ≤ 10 MB, aspect ratio between 1:2.5 and 2.5:1.

Typical generation time: 100–150 s for t2v / i2v / r2v. Suggested polling timeout: 5 minutes.

Both success and business failures return HTTP 200. A failed call carries an error object — { "error": { "message", "type", "code" }} — instead of the receipt fields; check for the error field to tell them apart.

Query and Download

Poll the task until it reaches SUCCESS or FAILURE (every 10–15 seconds, never below 5 seconds), then download the result. The download endpoint supports Range requests (HTTP 206) for resumable download and seek-while-playing.

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

GET/v1/videos/{task_id}/content

Response

schema

Core fields below. The full task detail schema, status lifecycle, and polling guidance are documented on the Video Generation page.

statusstringOptional

Task status.

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.

Submit a Generation Task

bashText to video (t2v)

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,
    "metadata": {
      "ratio": "16:9",
      "seed": 42,
      "watermark": false
    }
  }'

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
}

bashImage to video (i2v)

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-i2v",
    "prompt": "The camera slowly pushes in as the scene comes to life",
    "size": "720P",
    "duration": 5,
    "input_reference": "https://example.com/girl.jpg"
  }'

bashReference to video (r2v)

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-r2v",
    "prompt": "The woman in the red qipao from [Image 1] raises her hand and unfolds the fan from [Image 2]",
    "size": "720P",
    "duration": 5,
    "metadata": {
      "ratio": "16:9",
      "input": {
        "media": [
          { "type": "reference_image", "url": "https://example.com/girl.jpg" },
          { "type": "reference_image", "url": "https://example.com/folding-fan.jpg" }
        ]
      }
    }
  }'

Query and Download

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
}

bashDownload the result

Language

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

Model Lineup

Submit a Generation Task

Request

Response

Query and Download

Response

Related