Documentation Index
Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
Use this file to discover all available pages before exploring further.
Overview
HappyHorse (快马) is Alibaba’s video generation model series, focused on high-fidelity dynamic video generation — it precisely understands text semantics and outputs smooth, natural, detail-rich, high-quality videos that keep subjects stable. APIYI connects directly through the DashScope passthrough channel, so a single APIYI Key lets you call every HappyHorse capability. The current version, HappyHorse-1.0, covers four core use cases:| Use case | Model ID | Your input | Output |
|---|---|---|---|
| Text-to-Video | happyhorse-1.0-t2v | A text prompt | Short video |
| Image-to-Video | happyhorse-1.0-i2v | First-frame image + prompt | Brings a still image to life (no audio-driven support) |
| Reference-to-Video | happyhorse-1.0-r2v | Up to 9 reference images + prompt | Video with high-fidelity subject and scene preservation |
| Video Edit | happyhorse-1.0-video-edit | Video + up to 5 reference images + instruction | Locally/globally edited video |
model field. HappyHorse leans toward “high-fidelity dynamic video”; Reference-to-Video supports up to 9 reference images and Video Edit supports up to 5 reference images, with strong subject consistency. It shares the same endpoint as the Wan series and is directly interchangeable.Text-to-Video API
happyhorse-1.0-t2v, generate video from a pure text prompt.Image-to-Video API
happyhorse-1.0-i2v, generate video from a first-frame image (no audio-driven).Reference-to-Video API
happyhorse-1.0-r2v, up to 9 reference images to preserve the subject.Video Edit API
happyhorse-1.0-video-edit, edit video with up to 5 reference images.Why Choose APIYI for HappyHorse
One Key for all capabilities
Direct access, no VPN needed
api.apiyi.com, accessible from domestic data centers and home broadband.No charge on failure
failed state (unreachable media URL, sensitive prompt, etc.) are not billed, so retry with confidence.DashScope protocol passthrough
model name.Core Features
Four-in-one async endpoint
POST /wan/api/v1/...video-synthesis; after submission it returns a task_id, then you poll and download.High-fidelity subject preservation
Up to 9 reference images
happyhorse-1.0-r2v officially supports up to 9 reference_image entries, giving stronger subject consistency in multi-reference scenarios.Multiple resolutions and durations
prompt_extend smart rewriting to improve the quality of short prompts.Supported Models
| Model ID | Capability | Required media input | Notes |
|---|---|---|---|
happyhorse-1.0-t2v | Text-to-Video | None | Pure text generation |
happyhorse-1.0-i2v | Image-to-Video | first_frame | Does not support driving_audio |
happyhorse-1.0-r2v | Reference-to-Video | reference_image (up to 9) | Multi-reference subject preservation |
happyhorse-1.0-video-edit | Video Edit | video + reference_image (up to 5) | Model name has a hyphen |
⚠️ Endpoint Selection (Most Important)
APIYI mounts two paths simultaneously, and only the DashScope passthrough endpoint is fully usable for all HappyHorse capabilities:| Path | Protocol style | i2v / r2v availability | Conclusion |
|---|---|---|---|
/v1/videos | OpenAI flat style | ❌ Media fields are dropped | Do not use |
/wan/api/v1/services/aigc/video-generation/video-synthesis | DashScope native passthrough | ✅ Fully usable | Always use this one |
Async Call Flow
The whole flow is asynchronous, in three steps: create task → poll status → download video.Create task
POST /wan/api/v1/services/aigc/video-generation/video-synthesis, with the request header X-DashScope-Async: enable. It immediately returns a task_id.Poll status
GET /v1/tasks/{task_id} (with Authorization), querying every 5–10 seconds (not less than 3 seconds), until status becomes completed.Task Status Reference
| Status | Meaning | Next step |
|---|---|---|
submitted | Submitted, queued | Keep polling |
in_progress | Generating | Keep polling (progress often stalls at 30% — that’s the upstream’s coarse reporting granularity, not a stuck task) |
completed | Succeeded | Download from result_url |
failed | Failed | Check error.message / fail_reason |
Complete Python Client
Key Parameters Explained
When submitting, the body uses the DashScope nested structure:{ model, input: { prompt, media[] }, parameters: {...} }.
media[] Types
type | Purpose | Applicable models |
|---|---|---|
first_frame | First-frame image (≤1) | i2v, r2v |
reference_image | Reference image (up to 9 for r2v, up to 5 for video-edit) | r2v, video-edit |
video | Input video | video-edit |
parameters Fields
| Field | Type | Values | Notes |
|---|---|---|---|
resolution | string | 720P / 1080P | Uppercase, explicit specification recommended |
duration | int | 2–15 | Seconds (integer), commonly 5 / 10 |
prompt_extend | bool | true / false | Smart prompt rewriting, strongly recommended true |
watermark | bool | true / false | ”AI Generated” watermark in the bottom-right corner |
seed | int | 0–2147483647 | Fixing it improves reproducibility |
How to Choose HappyHorse vs. Wan
HappyHorse and Wan are both Alibaba video models that share the same endpoint and schema (interchangeable by just changing themodel name), but they emphasize different things:
| Dimension | HappyHorse-1.0 | Wan2.7 |
|---|---|---|
| Audio-driven lip-sync (i2v) | ❌ Not supported, i2v is first-frame only | ✅ wan2.7-i2v supports driving_audio |
| Reference-to-Video limit | Up to 9 reference images | Reference images + reference videos combined ≤5 |
| Video Edit reference images | ≤5 | ≤5 |
| Style emphasis | High-fidelity dynamic video, stable subjects | Multi-subject interaction, voice timbre reference |
Best Practices
Iterate first at 720P / 5 seconds
Poll every 5-10 seconds
Set a 20-minute client timeout as a safety net
Error Codes and Retries
| Source | Characteristics | Handling |
|---|---|---|
| Create stage (rejected by APIYI) | HTTP 4xx/5xx, with type of task_error / parse_request_failed / build_request_failed | Fix the body and retry (wrong field type, missing media, wrong endpoint) |
| Execution stage (rejected by upstream Alibaba Cloud) | Task status=failed, with error.message prefixed by a bracketed code like [InvalidParameter] / [InvalidImageUrl] | Read the bracketed hint; usually an unreachable media URL or a sensitive prompt |
failed task with [InvalidImageUrl] is retryable, while [InvalidParameter] / sensitive-word failures are not.FAQ
Is there any difference in how HappyHorse and Wan are integrated?
Is there any difference in how HappyHorse and Wan are integrated?
model field (e.g., wan2.7-t2v → happyhorse-1.0-t2v); the rest of the body stays identical.Why can't HappyHorse's i2v do lip-sync?
Why can't HappyHorse's i2v do lip-sync?
happyhorse-1.0-i2v does not support the driving_audio (audio-driven) field; i2v only accepts first_frame. For lip-sync / rap / digital-human voiceover, use Wan2.7-i2v.Can happyhorse-1.0-r2v really take 9 reference images?
Can happyhorse-1.0-r2v really take 9 reference images?
reference_image entries — just put them in the media array. More reference images give stronger consistency for the subject / clothing / scene.Why can't I submit via /v1/videos?
Why can't I submit via /v1/videos?
/v1/videos has incomplete support for the media field of i2v / r2v, causing the upstream to report [InvalidParameter] Field required: input.media. All create requests go through /wan/api/v1/services/aigc/video-generation/video-synthesis, and queries go through /v1/tasks/{task_id}.What if downloading result_url returns a 403?
What if downloading result_url returns a 403?
Authorization header. result_url is already a signed OSS direct link; adding your APIYI Key gets it rejected by OSS instead. result_url expires in 24 hours by default, so download it promptly.Are failed tasks billed?
Are failed tasks billed?
status=failed is not billed. But resubmitting the same task bills again, so handle idempotency.Group Setup
The HappyHorse and Wan series share a singleWan group — one Token can call both series (the Token in the screenshot is named Wan2.7&HappyHorse). Video models are billed per second, so the Token must meet two conditions to route successfully:
- Billing model: choose Pay-as-you-go Priority or Pay-as-you-go — video is billed per second, so Pay-per-request Tokens cannot route
- Group: select a group that includes
Wan

Pricing
Default price = 98% of Alibaba’s official price (simple to reason about)
In the console theWan group shows a rate of 0.14x, which is denominated in the built-in RMB pricing unit. Because APIYI bills in USD at a fixed 1:7 exchange rate, the effective conversion is:
Conversion: USD price per second = official RMB price × 0.14 (i.e. × 0.98 ÷ 7).
Price detail (default price, billed per second)
HappyHorse-1.0 text-to-video / image-to-video / reference-to-video are priced the same, with two tiers —720P / 1080P (480P is not supported):
| Resolution | Official price | Our default /s | 5 s | 10 s | 12 s |
|---|---|---|---|---|---|
720P | ¥0.9/s | $0.126/s | $0.63 | $1.26 | $1.51 |
1080P | ¥1.6/s | $0.224/s | $1.12 | $2.24 | $2.69 |
happyhorse-1.0-video-editoutput duration follows the source video and is billed by actual output seconds, not byduration.- Prices shown are the default (98% of official); with the maximum top-up bonus, the effective price is roughly the table value ÷ 1.2 (e.g. 1080P 5 s $1.12 → about $0.93).
Stack top-up bonuses for an even lower effective price
After joining the top-up bonus program, credited balance can be boosted up to ~1.2x, pushing the effective price lower still:| Tier | Effective price (vs Alibaba official) | Formula |
|---|---|---|
| Default | 98% | rate 0.14x × fixed exchange rate 7 |
| With top-up bonuses (max tier for large customers) | ~81.6% | 0.98 ÷ 1.2 |
- Billing dimension = resolution tier × duration (seconds); failed tasks are not billed.
- 1:7 is a fixed settlement exchange rate (not a preferential rate); it applies uniformly to all USD top-ups.
- For the highest bonus tiers and eligible channels, see top-up bonuses. The latest rate is authoritative in the console.
Related Documentation
Text-to-Video Playground
happyhorse-1.0-t2v online debuggingImage-to-Video Playground
happyhorse-1.0-i2v first-frame generationReference-to-Video Playground
happyhorse-1.0-r2v up to 9 reference imagesVideo Edit Playground
happyhorse-1.0-video-edit outfit swap / background swap