Create task

Submit an alibaba/happyhorse-1.0 video generation task through the site's unified asynchronous entry point.

Authorization

header

AuthorizationstringRequired

Bearer <your Amux key> Your Amux API key.

Request

application/json

modelstringRequired

The site-side model ID, or one of the three capability aliases

(happyhorse-1.0-t2v / -i2v / -r2v).

promptstring

What to generate. Up to **5,000 non-Chinese characters or 2,500

Chinese characters**; anything beyond is truncated upstream rather

than rejected.

For reference-image generation, use [Image 1] [Image 2] (with

square brackets) to refer to the reference images in media order.

mediaarray<object>

Input media. Public https URLs only. A first frame and reference

images are mutually exclusive — they belong to two different

capabilities.

›mediaarray<object>

type"first_frame" | "reference_image"Required

What this item is for — and **which upstream model gets

called**:

Role	Count	Calls	Format and limits
first_frame	exactly 1	-i2v	JPEG/JPG/PNG/WEBP, ≤20MB, shortest side ≥300px, aspect 1:2.5–2.5:1
reference_image	1–9	-r2v	Same as above

The two cannot be mixed. Mixing returns 400.

urlstringRequired

A public https URL. The model fetches it; we never do.

resolution"720P" | "1080P"Default "1080P"

Output resolution tier. This field is a pricing dimension.

⚠️ 1.0 has no 480P tier (1.1 does). Sending 480P returns 400.

aspect_ratio"16:9" | "9:16" | "4:3" | "3:4" | "4:5" | "5:4" | "1:1" | "9:21" | "21:9"Default "16:9"

Aspect ratio. This endpoint uses aspect_ratio; the Model Studio

endpoint calls the same thing ratio. There is no adaptive tier.

durationintegerDefault 5

Seconds of output, 3–15. This model has no -1 (automatic

duration) tier.

seedinteger

Random seed, for reproducible results.

watermarkbooleanDefault true

Whether to watermark the output. This model defaults to true.

webhook_urlstring

We POST the result here when the task reaches a terminal state. https

only, and it may not point at a private network. Signing and

verification are described in

Create task.

Response

200response

The task was created.

400response

Invalid parameters or media.

402response

Balance is not enough to cover the reservation for this call.

503response

No usable upstream route, or our in-flight task limit is reached.

Two differences from the Model Studio endpoint#

Everything else (routing, pricing, reservation, idempotency, rate limits, task records) is identical:

This endpoint is vendor-neutral: code written against it needs no changes when you add another video upstream, whereas the Model Studio endpoint applies by definition only to Model Studio's models.

One site-side ID, three upstream models#

Upstream splits HappyHorse by capability into three models; we aggregate them behind one ID. The input media decides which one is called:

You can also name a capability explicitly — all three official IDs work here and are exactly equivalent to the aggregate ID:

Once named, the media must match, otherwise you get a 400 rather than a silent switch to another capability: "you wrote -i2v, we called r2v" is invisible on the invoice, and by then the video already exists.

All three capabilities are priced identically; the choice only affects how the video is generated. The model echoed in logs and retrieve results is the name you wrote.

Input media#

The rules are identical to the Model Studio endpoint: a first frame and reference images are mutually exclusive, only public https URLs are accepted, and reference images are named in the prompt with [Image 1].

Differences from Wan#

Two families on the same protocol, with value domains that differ item by item. These are the changes to make when migrating from Wan:

Parameters this model does not have (audio / prompt_extend) are dropped, and the task's result_meta.notes says so — not an error, but not silent either.

Values outside the accepted range (duration: 30, say) return 400 with the accepted range; they are never silently replaced with a default.

Billing#

Video produces no tokens. You are charged the per-second rate of the chosen resolution tier × the seconds actually produced; input media is not charged separately. All three capabilities cost the same.

A reservation is held against the upper bound at submit time, settled against actual usage when the task finishes, and the difference is released. Failures and timeouts are not billed and the reservation is released. Per-tier rates are on the model's page in the model catalog.

Webhooks and idempotency#

Task lifecycle, webhook_url signing and verification, idempotency keys and Prefer: wait are described in Create task.

Errors#

type values and retry semantics are described in Errors and retries.

curl https://gateway.amux.ai/v1/tasks \
  -H "Authorization: Bearer $AMUX_API_KEY" \
  -d '{
    "model": "alibaba/happyhorse-1.0",
    "prompt": "A ginger cat running through fresh snow, slow motion",
    "resolution": "1080P",
    "duration": 5
  }'

{
  "id": "task_01M1VD9E8WRYVBR7ES10SNQQQT",
  "status": "queued",
  "model": "alibaba/happyhorse-1.0",
  "created_at": "<string>",
  "output": {
    "images": [
      {}
    ],
    "videos": [
      {
        "index": 0,
        "url": "<string>"
      }
    ]
  },
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0,
    "output_video_seconds": 0
  },
  "cost": "0.371307",
  "error": {
    "message": "<string>",
    "code": "<string>"
  }
}