Create video

Generate video with alibaba/happyhorse-1.0. The request body uses Alibaba Model Studio's own shape (nested input.* / parameters.*), so an existing DashScope client only needs its base_url pointed at Amux.

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

With the aggregate ID the media decides which one is called; with a

capability alias the alias wins and mismatched media returns 400.

inputobjectRequired

Provide at least one of prompt and media; both is fine too.

First-frame image to video works without a prompt; do not submit an

empty string just to fill the field — it hurts quality.

›inputobject

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, and say which object in the image you mean. This

is the syntax the upstream documents; another form is not an

error, but the reference will not take effect.

mediaarray<object>

Input media. Public https URLs only — the oss:// scheme and

base64 images that Alibaba Model Studio accepts are not accepted

here.

The two kinds are mutually exclusive: a first frame and

reference images belong to two different capabilities and cannot

be sent together.

›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 and names

the item that does not fit.

For first-frame generation the aspect ratio comes from the

image, so ratio has no effect.

urlstringRequired

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

parametersobject

Generation parameters, all optional. Anything you omit falls back

to the model's own default; we do not set them on your behalf.

⚠️ This model has no audio and no prompt_extend — output

always has sound, and prompts are not rewritten. Sending those two

drops them, and the task's result_meta.notes says so.

›parametersobject

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

Output resolution tier. This field is a pricing dimension —

the per-second rate follows the tier you pick.

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

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

Aspect ratio. There is no adaptive tier here — that one

belongs to Wan. For first-frame generation the ratio comes from

the image and this field has no effect.

durationintegerDefault 5

Seconds of output, 3–15.

⚠️ This model has no -1 (automatic duration) tier — that

one belongs to Wan. Sending -1, or anything outside the range,

returns 400 with the accepted range.

seedinteger

Random seed, for reproducible results. Random when omitted.

watermarkbooleanDefault true

Whether to watermark the output. This model defaults to true

(Wan defaults to false); pass false explicitly if you do not

want one.

webhook_urlstring

POSTs the result here once the task reaches a terminal state. The shape is

identical to the callback on POST /v1/tasks (the {event, sent_at, task}

envelope, an Amux-Signature header, and backoff retries).

This field is ours, not the vendor's. Model Studio async tasks do support

callbacks, but they are configured as EventBridge rules in the Alibaba Cloud

console -- the address cannot be passed per request. Without this field, callers

on this endpoint could only poll, while the same task submitted through the

unified endpoint gets pushed.

https only, and never a private address -- we send it from our servers. The

URL is validated at submit time, so a typo fails immediately rather than

after the task has run.

Response

200response

The task was created. The status is 200, not 202, matching Alibaba Model

Studio's own endpoint.

400response

Invalid parameters or media. Three common cases: media that does not match a

named capability, duration outside 3–15, and a ratio outside this model's

nine tiers. The message names the accepted values.

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. Retry later.

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.

Submitting returns a task ID#

This endpoint is asynchronous: it returns a task ID immediately, the video is generated in the background, and you poll for the result. Prefer: wait will almost always degrade to "not finished" here — its ceiling is 90 seconds, while this endpoint normally takes minutes.

The status code is 200, not 202, matching Alibaba Model Studio's own endpoint.

task_id is Amux's task ID, not the upstream's. Retrieve it with either the Model Studio shape or the unified endpoint; both return two renderings of the same task, and the latter also carries usage and cost.

Input media#

Every item in media carries a type naming its role, which also decides which upstream model gets called. Per-role counts, formats and size limits are in the parameter panel above under media[].type.

A first frame and reference images are mutually exclusive: they belong to two different capabilities, and sending both returns 400.

Media URLs must be public https. The oss:// scheme and base64 images that Alibaba Model Studio accepts are not accepted on either endpoint here; non-https URLs and URLs pointing at private network ranges return 400.

Three parameters worth knowing#

prompt is not required. The rule is "at least one of prompt and media". First-frame image to video works without a prompt; do not submit an empty string just to fill the field — it hurts quality.

Reference images must be named in the prompt. Use [Image 1] [Image 2] (with square brackets) to refer to the reference images in media order, and say which object in the image you mean. This is the syntax the upstream documents; another form is not an error, but the reference will not take effect.

resolution is a pricing dimension. Only 720P and 1080P (480P is 1.1 only). Sending 480P returns 400.

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.

Errors#

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

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

{
  "output": {
    "task_id": "<string>",
    "task_status": "PENDING",
    "video_url": "<string>",
    "code": "<string>",
    "message": "<string>"
  },
  "request_id": "<string>"
}