> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poyo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# H3 Max Video Generation

> Create videos from text, keyframes, or multimodal references

<Note>
  Check the live model catalog for availability before submitting a request.
</Note>

Successful submissions return a `task_id`. Use [Query Task Status](/api-manual/task-management/status) to retrieve the result, or supply `callback_url` at the top level to receive a notification when the task finishes or fails.

## 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.

## Parameters

* `prompt` is required, with up to 50,000 characters.
* `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 before credits are charged.

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 before charging.

## Examples

```json Text to video theme={null}
{
  "model": "h3-max",
  "input": {"prompt": "A cinematic aerial view of a coastal city at sunrise"}
}
```

```json Starting and ending frames theme={null}
{
  "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"]
  }
}
```

```json Multimodal references theme={null}
{
  "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"]
  }
}
```

## Billing

Output charges depend on duration and resolution. Each reference request includes a shared reference allowance; material above that allowance incurs an additional fee. The server calculates reference usage across images, video, and audio together. Do not supply token counts or media metadata in your request.


## OpenAPI

````yaml api-manual/video-series/h3-max.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: PoYo AI - H3 Max API
  description: >-
    Generate 5–15 second videos from text, keyframes, or image-led multimodal
    references.
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
    description: Production server
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - H3 Max
      summary: Submit H3 Max Task
      operationId: submitH3MaxTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              text-to-video:
                summary: Text To Video
                value:
                  model: h3-max
                  input:
                    prompt: A cinematic aerial view of a coastal city at sunrise
              image-to-video:
                summary: Image To Video
                value:
                  model: h3-max
                  input:
                    prompt: The camera moves forward as daylight turns into sunset
                    duration: 8
                    resolution: 1080p
                    image_urls:
                      - https://example.com/start.jpg
                      - https://example.com/end.jpg
              reference-to-video:
                summary: Reference To Video
                value:
                  model: h3-max
                  input:
                    prompt: >-
                      Image 1 follows the movement in Video 1 with the
                      atmosphere of Audio 1
                    duration: 10
                    resolution: 768p
                    aspect_ratio: adaptive
                    reference_image_urls:
                      - https://example.com/subject.jpg
                    reference_video_urls:
                      - https://example.com/motion.mp4
                    reference_audio_urls:
                      - https://example.com/atmosphere.wav
      responses:
        '200':
          description: Task submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
components:
  schemas:
    SubmitRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          enum:
            - h3-max
          example: h3-max
        callback_url:
          type: string
          format: uri
          description: Optional webhook callback URL.
        input:
          $ref: '#/components/schemas/H3MaxInput'
    SubmitResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
        data:
          type: object
          required:
            - task_id
            - status
            - created_time
          properties:
            task_id:
              type: string
              example: task-unified-1790245800-h3max01
            status:
              type: string
              example: not_started
            created_time:
              type: string
              format: date-time
              example: '2026-09-24T10:30:00Z'
              description: ISO 8601 timestamp when the task was created.
      example:
        code: 200
        data:
          task_id: task-unified-1790245800-h3max01
          status: not_started
          created_time: '2026-09-24T10:30:00Z'
    H3MaxInput:
      type: object
      additionalProperties: false
      required:
        - prompt
      description: >-
        At most 12 reference assets in total. All media URLs must use HTTP(S).
        Reference video and audio each require reference images. Media metadata
        and billing tokens are computed by the server.
      properties:
        prompt:
          type: string
          minLength: 1
          maxLength: 50000
          description: >-
            Describe the video. The prompt must not consist only of whitespace.
            Refer to assets as Image 1, Video 1, or Audio 1.
        duration:
          type: integer
          minimum: 5
          maximum: 15
          default: 5
        resolution:
          type: string
          enum:
            - 480p
            - 768p
            - 1080p
          default: 768p
        enable_safety_checker:
          type: boolean
          default: true
          description: >-
            If set to true, the safety checker will be enabled. Defaults to
            true.
        aspect_ratio:
          type: string
          enum:
            - '21:9'
            - '16:9'
            - '4:3'
            - '1:1'
            - '3:4'
            - '9:16'
            - adaptive
          description: >-
            Text mode defaults to 16:9 and does not accept adaptive. Reference
            mode defaults to adaptive. Not accepted with image_urls.
        image_urls:
          type: array
          maxItems: 2
          items:
            type: string
            format: uri
          description: >-
            Starting frame and optional ending frame; mutually exclusive with
            all references.
        reference_image_urls:
          type: array
          maxItems: 9
          items:
            type: string
            format: uri
          description: >-
            Subject or style images; required when reference video or audio is
            supplied. Supported shapes: 1:1, 4:3, 3:4, 16:9, 9:16, 5:2, 2:5.
        reference_video_urls:
          type: array
          maxItems: 3
          items:
            type: string
            format: uri
          description: >-
            Each clip must be 2–15 seconds; combined video duration must not
            exceed 15 seconds. Constant 24 fps, square pixels, no rotation
            metadata, and 16:9 or 9:16 are required. After capping frames at the
            requested output duration, counted frames must be 48, 120, 240, or
            360.
        reference_audio_urls:
          type: array
          maxItems: 3
          items:
            type: string
            format: uri
          description: >-
            Each clip must be 2–15 seconds; combined audio duration must not
            exceed 15 seconds. Requires 32 kHz and a decoded sample count
            divisible by 800. Each clip must not exceed the requested output
            duration.
      allOf:
        - not:
            required:
              - image_urls
            properties:
              image_urls:
                minItems: 1
            not:
              not:
                required:
                  - aspect_ratio
              properties:
                reference_image_urls:
                  maxItems: 0
                reference_video_urls:
                  maxItems: 0
                reference_audio_urls:
                  maxItems: 0
        - not:
            required:
              - aspect_ratio
            properties:
              aspect_ratio:
                enum:
                  - adaptive
              reference_image_urls:
                maxItems: 0
              reference_video_urls:
                maxItems: 0
              reference_audio_urls:
                maxItems: 0
        - not:
            required:
              - reference_video_urls
            properties:
              reference_video_urls:
                minItems: 1
            not:
              required:
                - reference_image_urls
              properties:
                reference_image_urls:
                  minItems: 1
        - not:
            required:
              - reference_audio_urls
            properties:
              reference_audio_urls:
                minItems: 1
            not:
              required:
                - reference_image_urls
              properties:
                reference_image_urls:
                  minItems: 1
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````