Hailuo 03 - PoYo AI

curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "hailuo-03",
  "input": {
    "prompt": "A cinematic aerial view of a coastal city at sunrise",
    "duration": 5,
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }
}
'

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8"
  }
}

{
  "code": 400,
  "error": {
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "code": 400,
  "error": {
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

POST

api

generate

submit

curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "hailuo-03",
  "input": {
    "prompt": "A cinematic aerial view of a coastal city at sunrise",
    "duration": 5,
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }
}
'

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "8FDN1I7M7Q68DDG8"
  }
}

{
  "code": 400,
  "error": {
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "code": 400,
  "error": {
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

After submission, a task_id will be returned. If you provided a callback_url, when the task status becomes finished or failed, a POST request will be sent to the callback_url.
Regardless of whether callback_url is provided, you can retrieve the result through the unified Query Task Status endpoint.

Models

hailuo-03 — Hailuo 03

Features

Text-to-Video: Generate a video directly from a prompt.
Image-to-Video: Provide one starting frame and an optional ending frame through image_urls.
Reference-to-Video: Guide the result with reference images, videos, and audio.
2K Output: The current output resolution is fixed at 2K.

Input modes

With no media input, the request uses text-to-video mode.
image_urls selects image-to-video mode. It accepts one starting frame and an optional second ending frame.
Any of reference_image_urls, reference_video_urls, or reference_audio_urls selects reference-to-video mode.
image_urls cannot be combined with any reference_*_urls field.
Reference images, videos, and audio can be combined in one reference-to-video request.
Reference audio cannot be the only reference input. Include at least one reference image or reference video.

Notes

prompt is required and accepts up to 2,000 characters.
duration accepts an integer from 5 through 15 seconds and defaults to 5.
resolution currently accepts only 2K.
Text-to-video supports 21:9, 16:9, 4:3, 1:1, 3:4, and 9:16. Its default is 16:9.
Reference-to-video supports the same fixed aspect ratios plus adaptive. Its default is adaptive.
Image-to-video follows the aspect ratio of the first image, so aspect_ratio is not accepted in that mode.
reference_image_urls accepts up to 9 images.
reference_video_urls accepts up to 3 video clips. Each clip should be 2–15 seconds, with a combined duration of at most 15 seconds.
reference_audio_urls accepts up to 3 audio clips. Each clip should be 2–15 seconds, with a combined duration of at most 15 seconds.
Mention reference assets in the prompt by modality and order, such as Image 1, Video 1, and Audio 1.
All media URLs must be publicly accessible and directly downloadable.

Authorizations

Authorization

string

header

required

All API endpoints require Bearer Token authentication.

Create an API key: sign in to PoYo, open Dashboard → API Key at poyo.ai/dashboard/api-key, and click to create a key.

Add it to the request header:

Authorization: Bearer YOUR_API_KEY

Body

application/json

model

enum<string>

required

Available options:

hailuo-03

Example:

"hailuo-03"

input

object

required

Show child attributes

callback_url

string<uri>

Optional webhook callback URL.

Response

Task submitted successfully

code

enum<integer>

Business status code. 200 means success; any other value means the request failed. Always check this field: some validation errors return HTTP 200 with code: 400 in the body.

200: Success
400: Invalid request parameters
401: Missing or invalid API key
402: Insufficient credits
403: Permission denied
404: Resource not found
408: Request timeout
429: Rate limit exceeded
500: Internal server error
502: Upstream service error
503: Service unavailable

See Error Codes for details.

Available options:

200,

400,

401,

402,

403,

404,

408,

429,

500,

502,

503

Example:

200

message

string

Example:

"success"

data

object

Show child attributes

​Models

​Features

​Input modes

​Notes

Authorizations

Body

Response

Models

Features

Input modes

Notes