H3 Max - PoYo AI

curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "h3-max",
  "input": {
    "prompt": "A cinematic aerial view of a coastal city at sunrise"
  }
}
'

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1790245800-h3max01",
    "status": "not_started",
    "created_time": "2026-09-24T10:30:00Z"
  }
}

{
  "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": "h3-max",
  "input": {
    "prompt": "A cinematic aerial view of a coastal city at sunrise"
  }
}
'

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1790245800-h3max01",
    "status": "not_started",
    "created_time": "2026-09-24T10:30:00Z"
  }
}

{
  "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

h3-max — H3 Max

Input modes

Mode	Input
Text to video	Supply a prompt with no media.
Image to video	Supply `image_urls` with a starting frame and, optionally, an ending frame.
Reference to video	Supply `reference_image_urls`; optionally add reference video and audio.

Starting and ending frames cannot be combined with any reference assets. Reference video and audio always require at least one reference image. Empty arrays do not select a mode.

Required parameters

prompt is required, with up to 50,000 characters.

Optional parameters

duration is an integer from 5 through 15 seconds; the default is 5.
resolution is 480p, 768p, or 1080p; the default is 768p.
enable_safety_checker (boolean) enables the safety checker when true. Defaults to true in every mode; set false to disable it.
image_urls accepts up to 2 images, in starting-frame and ending-frame order.
reference_image_urls accepts up to 9 images.
reference_video_urls accepts up to 3 clips. Each clip must be 2–15 seconds, and their combined duration must not exceed 15 seconds.
reference_audio_urls accepts up to 3 clips, also 2–15 seconds each and at most 15 seconds combined.
Reference images, videos, and audio must total at most 12 files.
Text mode supports 21:9, 16:9, 4:3, 1:1, 3:4, and 9:16, defaulting to 16:9.
Reference mode supports the same ratios plus adaptive, which is its default.
Image mode follows the starting image; do not pass aspect_ratio.

Media URLs must be publicly accessible HTTP(S) download links. Mention references in the prompt as Image 1, Video 1, and Audio 1, following the order in each list. The server checks reference metadata before submitting. If it cannot reliably determine the reference usage, the request is rejected. Reference images currently support 1:1, 4:3, 3:4, 16:9, 9:16, 5:2, and 2:5 shapes. Reference videos must use a constant 24 fps, square pixels, no rotation metadata, and a 16:9 or 9:16 shape. After limiting the counted frames to the requested output duration, the frame count must be 48, 120, 240, or 360. Reference audio must be 32 kHz with a decoded sample count divisible by 800, and each clip must not exceed the requested output duration. Other media formats or timing patterns are rejected.

Examples

Text to video

{
  "model": "h3-max",
  "input": {"prompt": "A cinematic aerial view of a coastal city at sunrise"}
}

Starting and ending frames

{
  "model": "h3-max",
  "input": {
    "prompt": "The camera glides forward as daylight turns into sunset",
    "duration": 8,
    "resolution": "1080p",
    "image_urls": ["https://example.com/start.jpg", "https://example.com/end.jpg"]
  }
}

Multimodal references

{
  "model": "h3-max",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "Image 1 follows the movement in Video 1 with the atmosphere of Audio 1",
    "duration": 10,
    "resolution": "768p",
    "reference_image_urls": ["https://example.com/subject.jpg"],
    "reference_video_urls": ["https://example.com/motion.mp4"],
    "reference_audio_urls": ["https://example.com/atmosphere.wav"]
  }
}

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:

h3-max

Example:

"h3-max"

input

object

required

At most 12 reference assets in total. All media URLs must use HTTP(S). Reference video and audio each require reference images. Media metadata is computed by the server.

Show child attributes

callback_url

string<uri>

Optional webhook callback URL.

Response

Task submitted successfully

code

enum<integer>

required

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

data

object

required

Show child attributes

​Models

​Input modes

​Required parameters

​Optional parameters

​Examples

Authorizations

Body

Response

Models

Input modes

Required parameters

Optional parameters

Examples