On this page

Video generationProduction Beta

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

Production Beta is callable now. Keep polling and failure handling in your integration while the video API remains in Beta.

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.

HTTP

Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY

Create a video generation

Creates an asynchronous Hailuo task and returns the live credits_reserved value calculated for this request.

POST/v1/videos/generations

Request

# 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": "768p",
    "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.

Legacy Beta

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 no faster than every 5 seconds. Video result URLs may be temporary, so download them promptly; Production Beta does not yet guarantee 7/30-day API video retention.

GET/v1/tasks/{task_id}

Request

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	768p or 1080p. 1080p supports only 6 seconds.
prompt_optimizer	boolean	No	Optimize the prompt. Default is true.

Responses

Accepted response example

{
  "id": "task_0123456789abcdef0123456789abcdef",
  "status": "pending",
  "model": "hailuo-2.3",
  "credits_reserved": 225
}

Completed response example

{
  "id": "task_0123456789abcdef0123456789abcdef",
  "status": "succeeded",
  "model": "hailuo-2.3",
  "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

pending

The task was accepted and is waiting to start.

processing

The model is generating the video.

succeeded

Generation finished and data contains the MP4.

failed

Generation failed. Read the sanitized error object.

Errors

400

Missing Idempotency-Key or malformed JSON.

401

Missing or invalid API key.

402

The account does not have enough credits.

403

The API account is disabled.

409

The idempotency key was reused with a different body.

413

The request body exceeds 64 KiB.

422

Invalid model, prompt, image, duration, or resolution.

429

Rate or concurrent-task limit reached.

5xx

The request could not be completed or submitted.

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

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

Production Beta is callable now. Keep polling and failure handling in your integration while the video API remains in Beta.

Make your first request

Create a task with a unique idempotency key, save the returned task ID, then poll until the result is ready.

Create an API key

Generate a key from your imya account settings.

Create a task

Choose Hailuo 2.3 or Hailuo 2.3 Fast and send the inputs.

Retrieve the result

Poll the task ID until it succeeds or fails.

# 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": "768p", "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" }'

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 }'

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	768p or 1080p. 1080p supports only 6 seconds.
prompt_optimizer	boolean	No	Optimize the prompt. Default is true.

Responses

Accepted response example

{
  "id": "task_0123456789abcdef0123456789abcdef",
  "status": "pending",
  "model": "hailuo-2.3",
  "credits_reserved": 225
}

Completed response example

{
  "id": "task_0123456789abcdef0123456789abcdef",
  "status": "succeeded",
  "model": "hailuo-2.3",
  "credits_used": 225,
  "data": [
    {
      "url": "https://media.example.com/generated/example.mp4"
    }
  ]
}

Errors

400

Missing Idempotency-Key or malformed JSON.

401

Missing or invalid API key.

402

The account does not have enough credits.

403

The API account is disabled.

409

The idempotency key was reused with a different body.

413

The request body exceeds 64 KiB.

422

Invalid model, prompt, image, duration, or resolution.

429

Rate or concurrent-task limit reached.

5xx

The request could not be completed or submitted.