Wan / HappyHorse: video generation API

HopBase exposes Wan and HappyHorse video generation through the official API contract, on the original paths. Code written against the official SDK or HTTP API migrates by changing only the base URL and the key — the request body, the response shape, and the paths are unchanged.

Available models

Wan 3.0 duration also accepts -1 for automatic. Its reference group takes up to 10 reference images, 5 reference videos, 5 reference audio tracks, 1 document, and 1 web link.

Use the exact IDs above. No aliases are registered; unknown model names are rejected. wan3.0-video-prime, happyhorse-1.1-video-edit, and the HappyHorse 1.0 line are not offered.

wan3.0-video and the happyhorse-1.1-* models are served by two separate groups — Wan 3.0 Official and HappyHorse 1.1 Official — so a key reaches a model only if it includes that model's group; one key can include both. Before sending paid work, confirm which models your key reaches with GET /v1/models.

Per-tier prices and full specs are on the model cards: wan3.0-video, happyhorse-1.1-t2v, happyhorse-1.1-i2v, happyhorse-1.1-r2v.

Request parameters

All requests use Authorization: Bearer sk-your-key and Content-Type: application/json. You do not need to send an async header; tasks are always asynchronous.

{
  "model": "wan3.0-video",
  "input": { "prompt": "...", "media": [{ "type": "first_frame", "url": "..." }] },
  "parameters": { "resolution": "1080P", "duration": 5 }
}

HappyHorse truncates Chinese prompts of 2,501-5,000 characters to about 2,500 without an error.

input.media

file accepts docx / doc / xlsx / xls / pptx / ppt / pdf / txt / key / pages / numbers / md.

For Wan 3.0, first / last frame input and the reference group (reference_*, file, link) are mutually exclusive.

url accepts an absolute public http(s) URL or a data: URI (base64). oss:// is rejected — the object belongs to your own cloud account, which the gateway cannot access.

Types, counts, and combinations are checked at submission; file size, dimensions, codec, durations, and page counts are checked by the service during execution. The whole JSON body is capped at 128 MiB including base64, so use URLs for large media.

parameters

A parameter the model does not support returns 400 instead of being ignored. The gateway always sends resolution and duration (defaults above); other omitted fields are not sent, so the service defaults apply.

Image-to-video example:

{
  "model": "happyhorse-1.1-i2v",
  "input": {
    "prompt": "The camera slowly pushes in, light drifting across the scene",
    "media": [{ "type": "first_frame", "url": "data:image/jpeg;base64,..." }]
  },
  "parameters": { "resolution": "720P", "duration": 5, "watermark": false }
}

Response

Submit response

A successful submit returns 200 with the HopBase task ID in the official response shape, in output.task_id (shaped like blt…):

{
  "output": {
    "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5",
    "task_status": "PENDING"
  },
  "request_id": "..."
}

Task query fields

Poll GET /api/v1/tasks/{task_id}.

output.task_status moves PENDING → RUNNING → SUCCEEDED | FAILED (uppercase); only the last two are terminal, so treat any other value as still running. A typical clip completes in 1-5 minutes; long Wan 3.0 clips take longer. Poll at roughly 15-second intervals.

In progress

{
  "output": {
    "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5",
    "task_status": "RUNNING"
  },
  "model": "wan3.0-video"
}

Succeeded

On success the response carries the output URL in output.video_url:

{
  "output": {
    "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5",
    "task_status": "SUCCEEDED",
    "video_url": "https://api.hop-base.com/...",
    "orig_prompt": "..."
  },
  "usage": { "video_count": 1, "duration": 5, "SR": 1080, "output_video_duration": 5, "input_video_duration": 0, "ratio": "16:9", "billed_seconds": 5, "billing_bucket": "1080p", "cost": 4.08, "cost_usd": 0.6, "currency": "CNY" }
}

Failed

A failed task is never billed. code is always TaskFailed, so read output.message (async task failures):

{ "output": { "task_id": "blt60x...", "task_status": "FAILED", "code": "TaskFailed", "message": "..." } }

Minimal example

BASE=https://api.hop-base.com
# 1. Submit
curl "$BASE/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "input": {
      "prompt": "Aerial shot of snow mountains above clouds at sunrise"
    },
    "parameters": {
      "resolution": "1080P",
      "duration": 5,
      "ratio": "16:9"
    }
  }'

# 2. Poll with the returned output.task_id, about every 15 seconds
curl "$BASE/api/v1/tasks/blt-your-task-id" \
  -H "Authorization: Bearer sk-your-key"

Notes

• Unknown fields and a second JSON value are rejected before the request goes out. This is deliberate.
• Reference media is downloaded on the official side, not by HopBase. Image hosts that block datacenter IPs (many free image CDNs do) cause the task to fail minutes after submission, so prefer data: embeds or your own object storage / CDN.
• Poll GET /api/v1/tasks/{task_id}. Note this path has no /v1 in front of /api, unlike the video endpoints on other pages. There is no list endpoint; keep track of task IDs on your side.
• A task still unfinished 2 hours after creation is failed automatically, and these tasks cannot be cancelled.
• output.video_url is a signed URL on api.hop-base.com, valid for 24 hours from the moment the task completes.
• Querying again returns the same URL without extending it, and an expired URL returns 410, so download results within that window.
• usage.ratio echoes the produced aspect ratio and may be raw dimensions (e.g. 1632:937) rather than one of the request enum values.

Common errors and fixes

Request errors return {"code":…,"message":…}.

The 413 and 404 message texts:

request body exceeds the 128 MiB limit (received N bytes)
invalid task ID format
task not found            # also returned for another user's key

Any other field (OpenAI's size / n / image, Wan 2.x's img_url / negative_prompt / shot_type, extra keys in media) returns 400:

400 {"code":"InvalidParameter","message":"request body does not match the JSON contract: json: unknown field \"size\""}

When a task fails, act on output.message:

Billing

Submitting a task checks available balance minus the estimates for in-flight tasks minus this request's own estimate; if that falls short you get a 402 with code insufficient_balance. The estimate is released automatically once the task ends. See Video overview for the details shared by every video family. A failed task is never billed.

Both series are billed by video duration in seconds, at a per-second unit price that varies by resolution tier — not by token:

charge = usage.billed_seconds × the rate for the usage.billing_bucket tier

usage.SR reports the generated video's resolution tier (480 / 720 / 1080) and is what selects it. The two series charge different rates at the same tier.

They differ in what the billable duration covers:

• wan3.0-video is billed on the input video as well as the output — billable duration = input video duration + output video duration — so usage.input_video_duration is added to the billed seconds; it reads 0.0 when the request carries no video input.
• The happyhorse-1.1-* models are billed on output only, and for reference-to-video the official documentation fixes input_video_duration at 0.

Once the task finishes, the query's top-level usage also carries cost_usd (the USD amount actually deducted from your balance for this task, 0 for an uncharged failure), cost (the same charge in CNY), and currency (always CNY).

Official list prices are on the pricing page. Your own rate is the one shown in the signed-in model catalog, and each request's actual charge is in your usage record.

Next steps

• Video overview — balance holds, timeouts, and result URLs shared by every video model
• MiniMax Hailuo H3 video API
• Error codes and retries — including async task failures
• Concurrency, timeouts, and billing