On this page
Hailuo 2.3 API
Create Hailuo 2.3 text-to-video and image-to-video tasks through one asynchronous API. Hailuo 2.3 Fast is available for lower-latency image-to-video.
REST API · v1 · Async tasks
Make your first request
Create a task with a unique idempotency key, save the returned task ID, then poll until the result is ready.
- 1
Create an API key
Generate a key from your imya account settings.
- 2
Create a task
Choose Hailuo 2.3 or Hailuo 2.3 Fast and send the inputs.
- 3
Retrieve the result
Poll the task ID until it succeeds or fails.
Authentication and idempotency
Send your API key as a Bearer token. Every generation POST also requires a unique Idempotency-Key so safe retries cannot create a second charge.
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEYCreate a video generation
Creates an asynchronous Hailuo task and returns the live credits_reserved value calculated for this request.
/v1/videos/generations# Text to video (Hailuo 2.3)
curl https://imya.ai/v1/videos/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hailuo-t2v-order-001" \
-d '{
"model": "hailuo-2.3",
"prompt": "A paper boat crossing a rain-soaked neon street",
"duration": 6,
"resolution": "720p",
"prompt_optimizer": true
}'
# Image to video (Hailuo 2.3 Fast)
curl https://imya.ai/v1/videos/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hailuo-i2v-order-001" \
-d '{
"model": "hailuo-2.3-fast",
"prompt": "Slow camera push-in with warm moving light",
"image_url": "https://cdn.example.com/first-frame.jpg",
"duration": 6,
"resolution": "1080p"
}'Legacy Beta compatibility
Existing integrations may keep using POST /api/video/generate with x-api-key, but generation POSTs now also require Idempotency-Key for safe retries. New integrations should use /v1/videos/generations.
curl https://imya.ai/api/video/generate \
-H "x-api-key: YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: legacy-hailuo-order-001" \
-d '{
"modelKey": "hailuo-2-3-standard-t2v",
"prompt": "A paper boat crossing a rain-soaked neon street",
"resolution": "720p",
"outputDurationSec": 6,
"promptExtend": true
}'Retrieve a task
Returns the latest task state, final credit usage, generated MP4, or a sanitized error. Poll at least 5 seconds apart; faster requests still count toward the rate limit but do not refresh upstream state. Video result URLs may be temporary, so download them promptly; the API does not guarantee 7/30-day video retention.
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"Request parameters
| Field | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | hailuo-2.3 or hailuo-2.3-fast. |
| prompt | string | Yes | Generation instructions, up to 5,000 characters. |
| image_url | string | Conditional | Public HTTPS first frame. Required for Fast; omit on standard text-to-video. |
| duration | number | No | 6 or 10 seconds. Default is 6. |
| resolution | string | No | 720p or 1080p. 1080p supports only 6 seconds. |
| prompt_optimizer | boolean | No | Optimize the prompt. Default is true. |
Responses
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "hailuo-2.3",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 225
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "hailuo-2.3",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:02:18.000Z",
"credits_reserved": 225,
"credits_used": 225,
"data": [
{
"url": "https://media.example.com/generated/example.mp4"
}
]
}Live credit billing
The server calculates credits_reserved from the selected model, workflow, resolution, duration, and the API key owner’s current plan. The numbers in the response examples illustrate the response shape only; always use the value returned for that request and never cache a Hailuo price in your client.
Task status
pendingThe task was accepted and is waiting to start.
processingThe model is generating the video.
succeededGeneration finished and data contains the MP4.
failedGeneration failed. Read the sanitized error object.
Errors
400Missing Idempotency-Key or malformed JSON.
401Missing or invalid API key.
402The account does not have enough credits.
403The API account is disabled.
404The task was not found or does not belong to this account.
409The idempotency key was reused with a different body.
413The request body exceeds 64 KiB.
415Content-Type must be application/json.
422Invalid model, prompt, image, duration, or resolution.
429Rate or concurrent-task limit reached.
5xxThe request could not be completed or submitted.
Shared Imya API contract
These rules apply to every public image and video generation endpoint. Model-specific fields and prices remain in the parameter table above.
Billing and safe retries
The exact credits shown in credits_reserved are deducted atomically when a new task is accepted. Replaying the same Idempotency-Key and request body returns the original task without a second charge.
Timeouts and refunds
A task that has not reached a terminal result within 30 minutes fails. Eligible credits are refunded once, and the refund keeps the original credit expiration date.
Rate and concurrency limits
Each API key can make up to 120 requests per 60 seconds. One account can run up to five image tasks or three video tasks at the same time. A 429 response may include Retry-After guidance; honor it when present.
Polling and task ownership
Poll GET /v1/tasks/{id} at least five seconds apart, using the id returned by task creation. Faster requests still count toward the API-key rate limit and do not refresh upstream state. Only the account that created a task can retrieve it. Webhooks, SDKs, and batch submission are not currently available.
Errors and content safety
Public errors are sanitized and never expose upstream credentials, internal URLs, or infrastructure details. Unsafe prompts can be rejected with prompt_blocked before generation starts.
Image result retention
Stored image results remain available for seven days on free accounts and up to 30 days on active paid or Lifetime accounts. After deletion, the response has status failed and error.code media_deleted instead of an empty success.
Hailuo 2.3 API production integration guide
Treat a reliable Hailuo 2.3 integration as a small asynchronous job system, not one long-running HTTP request. Persist the id returned for every Imya task and make retries deterministic. These practices cover production decisions.
Choose parameters from the model contract
Validate every request against this page's parameter table. During development, begin with the smallest supported input and output settings, then increase quality, dimensions, duration, or reference count only when the product requires it. Check user-provided prompt length, file type, and file size before calling the API.
For video workflows, allow only documented combinations of duration, resolution, aspect ratio, audio, and source media; do not silently replace an unsupported choice.
Design the asynchronous workflow for recovery
Submit the video task, store its returned id with your job record, and let a background worker retrieve status. Poll GET /v1/tasks/{id} at least five seconds apart. Faster requests still count toward the API-key rate limit but do not refresh upstream state. The public status is pending, processing, succeeded, or failed. Stop at a terminal state or the hard 30-minute deadline. Imya does not currently provide webhooks, SDKs, or batch submission, so integrate through direct HTTP requests and polling.
- 01Persist id, status, credits_reserved, and the request identity before updating the UI.
- 02Back off after transient network errors, respect Retry-After on 429 responses, and never turn a transport error into a new paid task automatically.
- 03Limit work per account: up to three concurrent video tasks. Each API key also has a limit of 120 requests per 60 seconds.
Make billing and retries deterministic
When a new task is accepted, the exact credits_reserved amount is deducted atomically. Generate one Idempotency-Key for each intended creation and save it with the request. Replaying that key with the same body returns the original task without another charge. A changed request needs a new key.
For an eligible failed task, Imya refunds credits once and preserves their original expiration date. The public status remains failed: error.code is refund_pending while settlement is processing, and credits_refunded appears when settlement completes. Reconcile by id; never issue credits in the client.
Protect credentials, ownership, and generated media
Keep API keys on your server, never in browser or mobile bundles. Associate each returned id with its authenticated user or workspace and verify ownership before displaying a result. Log request and task IDs for support without exposing prompts, private media URLs, or credentials.
Do not assume a fixed video retention period. After success, promptly copy required results into storage you control, with user consent and a clear privacy policy. Handle an unavailable media URL as a normal lifecycle event.
Production checklist
- Validate model-specific fields before submitting.
- Store one idempotency key and body per intended task.
- Persist state and poll at least five seconds apart.
- Enforce account concurrency and key rate limits.
- Handle the four public statuses explicitly; for failed responses, inspect error.code for media_deleted or refund_pending and credits_refunded for a completed refund.
- Keep credentials server-side and define result retention.
Common questions
How often should my worker poll?
Wait at least five seconds; use slower backoff while processing continues.
When are credits charged?
The exact credits_reserved amount is deducted atomically when a new task is accepted.
Can a retry charge twice?
Not when the same Idempotency-Key and identical body are replayed; the original task returns.
How should I handle terminal failure?
Show a clear error, retain id, and let the server complete any eligible one-time refund. Inspect credits_refunded instead of waiting for a separate refunded status.
Want to test Hailuo before integrating?
Open the hosted Hailuo 2.3 tool to compare Fast, standard, text, and image inputs.
Try Hailuo 2.3 online