# AI3D API v2 model: h3-max-image-to-video

Generate a video from a prompt and optional start/end frame images with MiniMax H3 Max. If no frame image is provided, Fal handles the request as text-to-video.

- AI3D model ID: `h3-max-image-to-video`
- Task: `image_to_video`
- AI3D provider adapter: `fal`
- Availability: Check `GET https://api.ai3d.dev/v2/models`; key model allowlists can further restrict access.
- Shared implementation guide: <https://api.ai3d.dev/v2/llms.txt>
- AI3D API reference: <https://api.ai3d.dev/v2/openapi.json>

## Request

Use the AI3D v2 job API. Do not call Fal directly or put provider credentials in the client.

- Method and URL: `POST https://api.ai3d.dev/v2/jobs`
- Authentication: `Authorization: Bearer <AI3D_API_KEY>` with write permission and this model allowed on the key.
- Content type: `application/json`
- Prompt: `input.prompt` is required (1–16,000 characters in AI3D; the provider accepts up to 50,000).
- Start frame: Optional top-level `image_url`, a public HTTPS URL. You can upload a PNG, JPEG, or WebP image up to 10 MiB with `POST /v2/uploads` first. Omit it for text-to-video; `input.end_image_url` can also provide only the last frame.
- Request body: `input` is optional model-specific JSON and is limited to 16 KiB. Defaults are:

```json
{
  "duration": 5,
  "resolution": "768P",
  "enable_safety_checker": true,
  "sync_mode": false,
  "prompt_expansion_mode": "balanced"
}
```

Supported `input` fields:

- `duration`: 0.92–15 seconds; default 5. Output may run up to about 0.7 seconds longer.
- `resolution`: `480P`, `768P`, or `1080P`; default `768P`.
- `seed`: optional integer or `null`.
- `enable_safety_checker`: optional boolean; defaults to `true`.
- `prompt_expansion_mode`: `disabled`, `balanced`, or `quality`; default `balanced`.
- `end_image_url`: optional public HTTPS URL for the final frame.
- `target_audio_url`: optional public HTTPS audio URL, or a short base64 audio data URI that fits within the 16 KiB input limit. Fal requires audio to be at least 2 seconds and accepts up to 15 MB; when audio is supplied, requested duration must be at least 2 seconds.
- `sync_mode`: must remain `false`; AI3D uses asynchronous jobs so it can archive and bill the result.

Example image-to-video request:

```json
{
  "model": "h3-max-image-to-video",
  "image_url": "https://example.com/opening-frame.png",
  "input": {
    "prompt": "The camera slowly pulls back as clouds drift overhead.",
    "duration": 5,
    "resolution": "768P",
    "prompt_expansion_mode": "balanced"
  }
}
```

Example text-to-video request:

```json
{
  "model": "h3-max-image-to-video",
  "input": {
    "prompt": "A small sailboat crosses a calm lake at sunrise.",
    "prompt_expansion_mode": "disabled"
  }
}
```

## Job lifecycle

1. Check `GET /v2/models` for availability and `GET /v2/billing/prices` for the current reservation estimate.
2. Submit the request to `POST /v2/jobs` with a fresh `Idempotency-Key` (letters, digits, `.`, `_`, `:`, or `-`; maximum 128 characters). A successful request returns `202 Accepted` and a job ID.
3. Poll `GET /v2/jobs/{job_id}` until the status is `succeeded`, `failed`, or `submission_unknown`.
4. On success, read `artifacts` and download the video through its authenticated `download_url`. Artifact names and formats depend on the provider response.

Fal's per-second rate varies by resolution and can change. AI3D reserves using the requested duration, selected resolution, and Fal's current unit price; final charges use Fal-reported billable units. Check `/v2/billing/prices` before submitting.

When retrying a timed-out submission, resend the identical body with the same idempotency key. Do not automatically create another job when status is `submission_unknown`.

## Provider reference

- https://fal.ai/models/minimax/h3-max/image-to-video/llms.txt