# HiAPI

> HiAPI is an AI model gateway that provides unified access to image, video, and audio generation models via one async API.

Base URL: https://api.hiapi.ai
Docs: https://www.hiapi.ai/docs

## Authentication

All requests require a Bearer token:

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Get your API key at: https://www.hiapi.ai/en/dashboard/api-keys

## Core Capabilities

All generation models — image, video, audio — are called through one unified async endpoint.

Endpoint: POST https://api.hiapi.ai/v1/tasks

Request body:
- `model` (string, required): HiAPI model name, e.g. `gpt-image-2/text-to-image`, `happyhorse-1-0`.
- `route` (string, optional): model route for models with multiple routes (e.g. `beta`, `ext`). `model: "x"` + `route: "ext"` is the preferred spelling of `model: "x@ext"` (the legacy `@` suffix keeps working). Omitted / `"default"` both mean the default route; an unknown route returns 400 listing the available routes.
- `input` (object, required): model-specific parameters; fields differ per model.
- `callback` (object, optional): `{ "url": "https://...", "when": "final" }` to receive a terminal POST instead of polling.

Optional request header `Idempotency-Key` (up to 255 bytes): retries with the same key under the same account create the task only once; replays return the original taskId with response header `Idempotent-Replay: true`. Same key + different body returns `422 IDEMPOTENCY_KEY_MISMATCH` (not retryable); while the first request is in flight you get `409 IDEMPOTENCY_KEY_PROCESSING` with `Retry-After` (retryable). Keys are kept 24 hours.

Returns `{ "code": 200, "data": { "taskId": "tk-hiapi-..." } }`. Poll `GET /v1/tasks/{taskId}` until `status` is `success` or `fail`. A task submitted with `route` echoes the field on the detail response, and `model` there holds the resolved full name (`x@ext`).

Image inputs (reference images, first/last frames, etc.) accept common raster formats such as JPEG/PNG/WebP (some models also accept GIF/BMP/TIFF; see each model page). SVG is not supported on any model: `.svg`/`.svgz` URLs and `image/svg+xml` data URIs are rejected with HTTP 400.

Models with confirmed input parameters:
- `gpt-image-2/text-to-image` — text-to-image for accurate text rendering, poster/layout work, product images, long prompts, and multi-format delivery. input: `prompt`, `aspect_ratio`, `resolution`.
- `gpt-image-2/text-to-image@pro` — higher-fidelity text-to-image for brand visuals, English prompts, and 2K output. input: `prompt`, `aspect_ratio`, `resolution`; `aspect_ratio` defaults to `1:1`, supports `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`; `resolution` supports `1K` and `2K`.
- `gpt-image-2/image-to-image` — image-to-image. input: `prompt`, `input_urls`, `aspect_ratio`, `resolution`.
- `gpt-image-2/image-to-image@pro` — Pro image-to-image editing/redrawing from 1-5 reference images. input: `prompt`, `input_urls`, `aspect_ratio`, `resolution`; `input_urls` is required with 1-5 public image URLs; `aspect_ratio` defaults to `auto`; `resolution` supports `1K` and `2K`.
- `gpt-image-2/text-to-image@ext` — high-resolution multi-ratio text-to-image: 16 aspect ratios (incl. 5:4, 4:5, 2:1, 21:9) at 1K/2K/4K with three quality tiers. input: `prompt`, `aspect_ratio`, `resolution`, `quality`; `resolution` and `quality` are required; billed by quality x resolution.
- `gpt-image-2/image-to-image@ext` — high-resolution multi-ratio image-to-image with up to 16 reference images. input: `prompt`, `image_urls`, `aspect_ratio`, `resolution`, `quality`; `image_urls` accepts 1-16 URLs or data URIs; `resolution` and `quality` are required.
- `Nano-Banana` — fast text-to-image. input: `prompt`, `aspect_ratio`, `output_format`; do not use the legacy `image_size` field in new requests.
- `Nano-Banana-2` — balanced image generation/editing with optional references. input: `prompt`, `image_input`, `aspect_ratio`, `resolution`, `output_format`.
- `Nano-Banana-Pro` — image generation/editing. input: `prompt`, `image_input`, `aspect_ratio`, `resolution`, `output_format`.
- `flux-1.1-pro` — photorealistic image generation. input: `prompt`, `image_prompt`, `aspect_ratio`, `width`, `height`, `safety_tolerance`, `seed`, `prompt_upsampling`, `output_format`, `output_quality`.
- `qwen-image-2.0` — low-cost image generation with strong Chinese text rendering. input: `prompt`, `size`, `negative_prompt`, `prompt_extend`, `watermark`, `seed`; `size` uses star-separated values such as `2048*2048` or `1328*1328`; `prompt_extend` should be presented to users as prompt optimization / 优化提示词; `seed` is an integer in `0..2147483647`.
- `flux-2/text-to-image` — high-fidelity text-to-image (FLUX.2 Pro) with strong prompt adherence and crisp in-image text. input: `prompt`, `aspect_ratio`, `width`, `height`, `resolution`, `output_format`, `output_quality`, `safety_tolerance`, `seed`; `resolution` is a megapixel tier `0.5 MP`/`1 MP` (default)/`2 MP`/`4 MP` and is ignored when `aspect_ratio` is `custom`; `width`/`height` (256-2048, rounded to multiples of 16) apply only with `aspect_ratio=custom`; `output_quality` (0-100, default 80) only affects webp/jpg; `safety_tolerance` is 1 (strict) to 5 (permissive), default 2; no negative prompt support; billed per image by resolution tier.
- `flux-2/image-to-image` — FLUX.2 pro-tier image editing: multi-reference composition, background replacement, style/material edits. input: `prompt`, `image_urls`, `aspect_ratio`, `resolution`; all required; `image_urls` 1-8 reference images, `aspect_ratio` supports `auto` (follows first input), `resolution` 1K/2K; billed per image by resolution tier.
- `flux-schnell/text-to-image` — ultra-fast budget text-to-image (FLUX.1 Schnell, 1-4 steps). input: `prompt`, `aspect_ratio`, `num_inference_steps`, `guidance_scale`, `output_format`, `seed`, `enable_safety_checker`; `num_inference_steps` is 1-12 (default 4, official recommendation is 1-4); `guidance_scale` is an upstream-compat parameter — schnell is timestep-distilled and the official implementation ignores guidance, keep the default; prompts are truncated around 256 T5 tokens, keep them concise.
- `wan2.7-image/text-to-image` — Tongyi Wanxiang Wan 2.7 Image Pro text-to-image with up to 4K output. input: `prompt`, `aspect_ratio`, `resolution`, `thinking_mode`, `seed`; `prompt` is 1-5000 characters (Chinese and English both work well); `aspect_ratio` includes ultra-wide `8:1`/`1:8` banner tiers; `resolution` is `1K`/`2K` (default)/`4K`, all tiers billed the same per image; `thinking_mode` (default false) improves output quality at the cost of latency; upstream image URLs expire in 24 hours, download or persist promptly.
- `z-image` — Tongyi Z-Image Turbo: efficient photorealistic text-to-image with accurate bilingual in-image text rendering. input: `prompt`, `aspect_ratio`; `prompt` is capped at 1000 characters (800 or fewer recommended), put the subject and any text to render first; no seed or negative prompt parameters (distilled model without CFG); output variety for identical prompts is low — rephrase the prompt for variations.
- `seedream-5.0-lite/text-to-image` — reasoning-guided text-to-image with real-time web knowledge and accurate multilingual text rendering (posters, menus, infographics). input: `prompt`, `aspect_ratio`, `resolution`; all three required; `aspect_ratio` defaults to `1:1`, supports `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `2:3`, `3:2`, `21:9`; `resolution` is `2K` (default, ≈2300px long edge) or `4K` (≈4096px long edge); both tiers billed the same per image; spell out any text you want rendered in the prompt.
- `seedream-4.5/text-to-image` — ByteDance Seedream 4.5 quality-tier text-to-image with photorealism and in-image text rendering. input: `prompt`, `aspect_ratio`, `resolution`; all required; 8 ratios, `resolution` 2K/4K (same price); billed per image.
- `seedream-5.0-pro/text-to-image` — HiAPI flagship text-to-image with upgraded fidelity and sharp in-image text rendering (posters, signage, photorealistic portraits). input: `prompt`, `aspect_ratio`, `resolution`, `output_format`; first three required; `prompt` 3-4000 chars; `aspect_ratio` defaults to `1:1`, supports `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `2:3`, `3:2`, `21:9`; `resolution` defaults to `2K`: `1K` ($0.05/image) or `2K` ($0.10/image); `output_format` `png` (default) or `jpeg`; billed per image by resolution tier.
- `grok-imagine/text-to-image` — xAI Grok Imagine standard text-to-image: fast, low-cost, 13 aspect ratios. input: `prompt` (required), `aspect_ratio`, `resolution` (1k/2k, same price), `output_format`; billed per image.
- `grok-imagine/image-to-image` — Grok Imagine standard image editing with 1-3 reference images, aspect `auto` follows the first input. input: `prompt`, `image_urls` (required), `aspect_ratio`, `resolution`, `output_format`; billed per image.
- `grok-imagine-quality/text-to-image` — xAI official Grok Imagine quality-tier text-to-image (standalone model): hero-grade detail, materials, and lighting. input: `prompt` (required), `aspect_ratio`, `resolution` (1k/2k price tiers, no 4k), `output_format`; billed per image by resolution tier.
- `grok-imagine-quality/image-to-image` — Grok Imagine quality-tier image editing (standalone model): stronger consistency and detail preservation. input: `prompt`, `image_urls` (required, 1-3 references), `aspect_ratio` (`auto` follows first input), `resolution` (1k/2k price tiers), `output_format`; billed per image by resolution tier.
- `seedream-4.5/image-to-image` — Seedream 4.5 unified generation-editing with up to 14 reference images. input: `prompt`, `image_urls`, `aspect_ratio`, `resolution`; all required; `image_urls` 1-14 refs; billed per output image.
- `seedream-5.0-lite/image-to-image` — instruction-based image editing with up to 14 reference images: recolor, in-image text rewriting, material swaps, multi-reference composites; unmentioned areas stay intact. input: `prompt`, `image_urls`, `aspect_ratio`, `resolution`; `image_urls` is required with 1-14 public image URLs (JPEG/PNG/WebP, ≤10MB each); `aspect_ratio` and `resolution` behave the same as the text-to-image variant; billed per output image regardless of reference count.
- `seedream-5.0-pro/image-to-image` — HiAPI flagship image editing with 1-10 reference images for consistent edits and multi-reference composites; preserves layout and in-image text when instructed. input: `prompt`, `image_urls`, `aspect_ratio`, `resolution`, `output_format`; first four required; `prompt` 3-4000 chars; `image_urls` 1-10 URLs (JPG/PNG/WebP, up to 10MB each; SVG not supported); `aspect_ratio` defaults to `1:1`, supports `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `2:3`, `3:2`, `21:9`; `resolution` defaults to `2K`: `1K` ($0.06/image) or `2K` ($0.10/image); `output_format` `png` (default)/`jpeg`; billed per output image by resolution tier.
- `Nano-Banana-2-Lite` — entry tier of the Nano Banana family: low-latency 1K image generation at an ultra-low flat price, with optional editing/remixing. input: `prompt`, `image_urls`, `aspect_ratio`; `prompt` and `aspect_ratio` are required; `image_urls` accepts up to 10 optional reference images (JPEG/PNG/WebP, ≤30MB each); `aspect_ratio` defaults to `auto`, supports 15 ratios including ultra-wide `8:1`/`1:8`; output is fixed 1K resolution.
- `qwen-image-2.0-pro` — professional tier of Qwen Image 2.0: stronger in-image text rendering, finer photorealism, better adherence, up to 2048x2048 (not 4K). input: `prompt`, `size`, `negative_prompt`, `prompt_extend`, `watermark`, `seed`; only `prompt` required; `size` is star-separated width*height (total pixels 512x512..2048x2048, default `2048*2048`); set `prompt_extend` to false when the image must contain exact text; sync-only upstream, still called via the async task API.
- `ideogram-v4` — typography specialist: best-in-class in-image text accuracy for logos, posters and signage (English strongest). input: `prompt`, `aspect_ratio`, `rendering_speed`, `output_format`, `seed`; `prompt` and `rendering_speed` required; `rendering_speed` is `TURBO`/`BALANCED`/`QUALITY` and price differs per tier; `aspect_ratio` presets are ~1MP (`1:1`, `16:9`, `4:3`, `9:16`, `3:4`); billed per image by rendering_speed tier.
- `grok-imagine-1.5/image-to-video` — xAI Grok Imagine 1.5 image-to-video with upgraded motion quality over 1.0. input: `image_urls`, `prompt`, `aspect_ratio`, `resolution`, `duration`; `image_urls` is required with exactly 1 image (JPEG/PNG/WebP ≤20MB); `duration` is any integer 1-15 seconds (default 8); `resolution` is `480p` (default) or `720p`; `aspect_ratio` defaults to `auto` (follows input); billed per second by resolution tier, same rates as grok-imagine 1.0.
- `minimax-music-1.5` — full-song music generation up to ~4 minutes with natural vocals (English and Chinese). input: `prompt`, `lyrics`, `audio_format`, `bitrate`, `sample_rate`; `prompt` (style, 10-300 chars) and `lyrics` (10-600 chars, `\n`-separated, supports [intro][verse][chorus][bridge][outro] tags) are required; output defaults to mp3 256kbps/44.1kHz; billed per song regardless of duration.
- `minimax-music-2.6` — full-song music generation with natural vocals (English and Chinese), instrumental mode and auto-lyrics. input: `prompt`, `lyrics`, `is_instrumental`, `sample_rate`, `bitrate`, `audio_format`; only `prompt` (style, max 2000 chars) is required; `lyrics` up to 3500 chars with 14 structure tags, leave empty to auto-generate; billed per song regardless of duration.
- `happyhorse-1-0` — text-to-video. input: `prompt`, `aspect_ratio`, `duration`, `resolution`, `seed`.
- `seedance-2-0` — video. input: `prompt`, `aspect_ratio`, `duration`, `resolution`, `first_frame_url`, `last_frame_url`, `reference_image_urls`, `reference_video_urls`, `reference_audio_urls`, `return_last_frame`, `generate_audio`, `web_search`; `resolution` supports `480p`, `720p`, `1080p`, `4k`; the online playground should render first/last/reference media as file upload controls from backend schema.
- `grok-imagine/text-to-video` — text-to-video. input: `prompt`, `aspect_ratio`, `mode`, `duration`, `resolution`; `mode` supports `fun`, `normal`; `duration` is 6-30 seconds; `resolution` supports `480p`, `720p`.
- `grok-imagine/image-to-video` — image-to-video. input: `image_urls`, `prompt`, `aspect_ratio`, `mode`, `duration`, `resolution`; `image_urls` accepts up to 7 reference images and should render as file upload controls; `duration` is 6-30 seconds; `resolution` supports `480p`, `720p`.
- `seedance-2.0-mini` — video (text-to-video and image-to-video). input: `prompt`, `resolution`, `duration`, `aspect_ratio`, `generate_audio`, `first_frame_url`, `last_frame_url`, `reference_image_urls`, `reference_video_urls`, `reference_audio_urls`; `resolution` is `480p`/`720p` (up to 720P), `duration` is an integer 4-15 seconds (default 5), billed per second tiered by resolution and `generate_audio`; passing `first_frame_url` switches to image-to-video; the playground should render first/last/reference media as file upload controls from backend schema.
- `seedance-2.0-fast` — video (text-to-video, image-to-video, and multimodal reference-to-video). input: `prompt`, `aspect_ratio`, `resolution`, `duration`, `generate_audio`, `first_frame_url`, `last_frame_url`, `reference_image_urls`, `reference_video_urls`, `reference_audio_urls`, `web_search`; `resolution` is `480p`/`720p` (default `720p`), `duration` is an integer 4-15 seconds (default 5), billed per second tiered by resolution and whether reference video input is present; image-to-video (first/last frame) and multimodal reference-to-video are mutually exclusive; the playground should render first/last/reference media as file upload controls from backend schema.
- `veo-3.1-fast/text-to-video` — text-to-video. input: `prompt`, `aspect_ratio`, `resolution`, `duration`, `generate_audio`, `negative_prompt`, `seed`; `resolution` is `720p`/`1080p`/`4k`, `duration` is `4`/`6`/`8` seconds, billed per second; `generate_audio` toggles native audio and increases price; text-to-video only, no reference image input.
- `veo-3.1/text-to-video` — text-to-video (flagship quality). input: `prompt`, `aspect_ratio`, `resolution`, `duration`, `generate_audio`, `negative_prompt`, `seed`; `resolution` is `720p`/`1080p`/`4k`, `duration` is `4`/`6`/`8` seconds, billed per second; `generate_audio` toggles native audio and increases price; cinematic quality tier of the Veo 3.1 family.
- `veo-3.1/image-to-video` — image-to-video (flagship quality). input: `prompt`, `image_url`, `aspect_ratio`, `resolution`, `duration`, `generate_audio`, `negative_prompt`, `seed`; `image_url` is the still image to animate (720p+ in 16:9 or 9:16 recommended); `aspect_ratio` is `auto`/`16:9`/`9:16` (auto follows the input image); `resolution` is `720p`/`1080p`/`4k`, `duration` is `4`/`6`/`8` seconds, billed per second.
- `veo-3.1-fast/image-to-video` — image-to-video (fast tier). input: `prompt`, `image_url`, `aspect_ratio`, `resolution`, `duration`, `generate_audio`, `negative_prompt`, `seed`; `image_url` is the still image to animate (720p+ in 16:9 or 9:16 recommended); `aspect_ratio` is `auto`/`16:9`/`9:16`; `resolution` is `720p`/`1080p`/`4k`, `duration` is `4`/`6`/`8` seconds, billed per second; faster and cheaper than `veo-3.1/image-to-video`.
- `happyhorse-1.1/text-to-video` — text-to-video. input: `prompt`, `resolution`, `aspect_ratio`, `duration`; `resolution` is `720p`/`1080p`, `duration` is an integer 3-15 seconds (default 5), billed per second by resolution; native audio is always on; text-to-video only, no image input.
- `happyhorse-1.1/image-to-video` — image-to-video. input: `image_urls`, `prompt`, `resolution`, `duration`; `image_urls` is exactly 1 first-frame image URL shown as a file upload in the online playground; `resolution` is `720p`/`1080p`, `duration` is an integer 3-15 seconds (default 5), billed per second; native audio is always on.
- `happyhorse-1.1/reference-to-video` — reference-to-video. input: `prompt`, `reference_image`, `resolution`, `aspect_ratio`, `duration`; `reference_image` is 1-9 reference image URLs referenced in the prompt as `[Image 1]`, `[Image 2]`, shown as file uploads in the online playground; `resolution` is `720p`/`1080p`, `duration` is an integer 3-15 seconds (default 5), billed per second; native audio is always on.
- `wan2.7-video/text-to-video` — text-to-video. input: `prompt`, `negative_prompt`, `audio_url`, `resolution`, `ratio`, `duration`, `prompt_extend`, `watermark`, `seed`; use `resolution` + `ratio`, not old `size` or `aspect_ratio`; `audio_url` is shown as an audio file upload in the online playground, and the backend may convert it to a hosted upstream URL; `seed` is an integer in `0..2147483647`; `prompt_extend` should be presented to users as prompt optimization / 优化提示词.
- `wan2.7-video/image-to-video` — image-to-video. input: `prompt`, `media[]`, `negative_prompt`, `resolution`, `duration`, `prompt_extend`, `watermark`, `seed`; `media[]` items are `{ "type": "first_frame" | "last_frame" | "driving_audio" | "first_clip", "url": "https://..." }`; playground image/audio/video references are rendered as file uploads where the backend schema exposes uploadable media fields.
- `kling-3.0-omni/text-to-video` — text-to-video. input: `prompt`, `resolution`, `aspect_ratio`, `duration`, `sound`; `resolution` is `720p`/`1080p`/`4K`, `duration` is an integer 3-15 seconds (default 5), billed per second by resolution; `sound` toggles native audio (multilingual dialogue and lip sync) and increases price; text-to-video only.
- `kling-3.0-turbo/text-to-video` — Kling 3.0 speed tier for text-to-video: 3-15s, 720p/1080p, lip-synced quoted dialogue. input: `prompt` (required), `duration` (3-15s), `resolution` (720p/1080p price tiers), `aspect_ratio` (16:9/9:16/1:1); billed per second by resolution.
- `hailuo-2.3/text-to-video` — MiniMax Hailuo 2.3 standard text-to-video with excellent motion physics. input: `prompt` (required), `duration` (6/10s price tiers), `prompt_optimizer`; billed per video.
- `hailuo-2.3/image-to-video` — Hailuo 2.3 standard image-to-video, first-frame driven. input: `prompt`, `image_url` (required, single URL string), `duration` (6/10), `prompt_optimizer`; billed per video.
- `hailuo-2.3-fast/image-to-video` — Hailuo 2.3 Fast, the family price floor for image-to-video. input: `prompt`, `image_url` (required), `duration` (6/10 price tiers), `prompt_optimizer`; billed per video. No text-to-video variant upstream.
- `kling-3.0-turbo/image-to-video` — Kling 3.0 speed tier for image-to-video, first-frame driven. input: `prompt`, `image_urls` (required, single first-frame image), `duration` (3-15s), `resolution` (720p/1080p price tiers); output aspect follows the input image; billed per second.
- `kling-3.0-omni/image-to-video` — image-to-video. input: `image_urls`, `prompt`, `resolution`, `duration`, `sound`; `image_urls` is 1 first-frame image URL or 2 `[first, last]` frame image URLs (JPEG/PNG/WEBP) shown as file uploads in the online playground; `resolution` is `720p`/`1080p`/`4K`, `duration` is an integer 3-15 seconds (default 5), billed per second; `sound` toggles native audio and increases price.
- `elevenlabs/text-to-dialogue` — text-to-dialogue (multi-speaker speech). input: `dialogue[]`, `language_code`, `stability`; `dialogue[]` items are `{ "text": "...", "voice": "<voice_id>" }` synthesized in order into one conversation audio, total `text` characters across all items must not exceed 5000 (over-limit returns 400); `voice` is one of 67 preset voice IDs (default James); `language_code` is an ISO code, empty string auto-detects; `stability` is one of `0`/`0.5`/`1` (default 0.5); billed per character; output is MP3.
  - preset voices (name=voice_id, 67 total): James=EkK5I93UQWFDigLMpZcX, Arabella=Z3R5wn05IrDiVCyEkUrK, Bradford=NNl6r8mD7vthiJatiJt1, Xavier=YOq2y2Up4RgXP2HyXjE5, Kuon=B8gJV1IhpuegLxdpXFOE, Monika Sogam=2zRM7PkgwBPiau2jvVXc, Mark=1SM7GgM6IMuvQlz2BwM3, Adeline=5l5f8iK3YPeGga21rQIX, Sam=scOwDtmlUjD3prqpp97I, Spuds Oxley=NOpBlnGInO9m6vDvFkFC, Eve=BZgkqPqms7Kj9ulSkVzn, Northern Terry=wo6udizrrtpIxWGp2qJk, British Football Announcer=gU0LNdkMOQCOrPrwtbee, Brock=DGzg6RaUqxGRTHSBjfgF, Nathan=x70vRnQBMBu4FAYhjJbO, Anika=Sm1seazb4gs7RSlUVw7c, Viraj=P1bg08DkjqiVEzOn76yG, Taksh=qDuRKMlYmrm8trt5QyBn, Horatius=qXpMhyvQqiRxWQs4qSSB, Liam=TX3LPaxmHKxFdv7VOQHJ, Callum=N2lVS1w4EtoT3dr4eOWO, Laura=FGY2WhTYpPnrIDTdsKH5, Brittney=kPzsL2i3teMYv0FxEYQ6, Mark=UgBBYS2sOqTuMpoF3BR0, Bella=hpp4J3VqNfWAUOO0d1Us, Brian=nPczCjzI2devNBz1zQrb, Hope=uYXf8XasLslADfZ2MB4u, Jeff=gs0tAILXbY5DNrJrsM6F, Jamahal=DTKMou8ccj1ZaWGBiotd, Finn=vBKc2FfBKJfcZNyEt1n6, Tom=DYkrAHD8iwork3YSUBbs, Cassidy=56AoDkrOh6qfVPDXZ7Pt, Addison 2.0=eR40ATw9ArzDf9h3v7t7, Jessica Anne Bogart=g6xIsTj2HwM6VR4iXFCw, Lucy=lcMyyd2HUfFzxdCaC4Ta, Tiffany=6aDn1KB0hjpdcocrUkmq, Felix=Sq93GQT4X1lKDXsQcixO, Jessica Anne Bogart=flHkNRp1BlvT73UL6gyz, Lutz=9yzdeviXkFddZ4Oz8Mok, Emma=pPdl9cQBQq4p6mRkZy2Z, Edward=zYcjlYFOd3taleS0gkk3, Marshal=nzeAacJi50IvxcyDnMXa, John Morgan=ruirxsoakN0GWmGNIo04, Aria=TC0Zp7WVFzhA8zpTlRqV, Viking Bjorn=ljo9gAlSqKOvF6D8sOsX, Pirate Marshal=PPzYpIqttlTYA83688JI, Johnny Kid=8JVbfL6oEdmuxKn5DK2C, Hope=iCrDUkL56s3C8sCRl7wb, Ana Rita=wJqPPQ618aTW29mptyoc, John Doe=EiNlNiXeDU1pqqOPrYMO, Burt Reynolds™=4YYIPFl9wE5c4L2eu2Gb, Hank=6F5Zhi321D3Oq7v1oNT4, Wyatt=YXpFCvM1S3JbWEJhoskW, Phil=LG95yZDEHg6fCZdQjLqj, Johnny Dynamite=CeNX9CMwmxDxUF5Q2Inm, Rachel M=aD6riP1btT197c6dACmy, Rex Thunder=mtrellq69YZsNwzUSyXh, Ed=dHd5gvgSOzSfduK4CvEg, Jean=eVItLK1UvXctxuaRV2Oq, Britney=esy0r39YPLQjOczyOib8, Sven=Tsns2HvNFKfGiNjllgqo, Viraj=1U02n4nD6AdIZ9CjF053, Nathaniel=AeRdCCKzvd23BpJoofzx, Benjamin=LruHrtVF6PSyGItzMNHS, Allison=1wGbFxmAM3Fgw63G1zZJ, Theodore HQ=hqfrgApggtO1785R4Fsn, Leon=MJ0RnG71ty4LH3dvNfSd.
  - language_code values (73 + auto): "" (auto-detect), af (Afrikaans), ar (Arabic), hy (Armenian), as (Assamese), az (Azerbaijani), be (Belarusian), bn (Bangla), bs (Bosnian), bg (Bulgarian), ca (Catalan), ceb (Cebuano), ny (Nyanja), hr (Croatian), cs (Czech), da (Danish), nl (Dutch), en (English), et (Estonian), fil (Filipino), fi (Finnish), fr (French), gl (Galician), ka (Georgian), de (German), el (Greek), gu (Gujarati), ha (Hausa), he (Hebrew), hi (Hindi), hu (Hungarian), is (Icelandic), id (Indonesian), ga (Irish), it (Italian), ja (Japanese), jv (Javanese), kn (Kannada), kk (Kazakh), ky (Kyrgyz), ko (Korean), lv (Latvian), ln (Lingala), lt (Lithuanian), lb (Luxembourgish), mk (Macedonian), ms (Malay), ml (Malayalam), zh (Chinese), mr (Marathi), ne (Nepali), no (Norwegian), ps (Pashto), fa (Persian), pl (Polish), pt (Portuguese), pa (Punjabi), ro (Romanian), ru (Russian), sr (Serbian), sd (Sindhi), sk (Slovak), sl (Slovenian), so (Somali), es (Spanish), sw (Swahili), sv (Swedish), ta (Tamil), te (Telugu), th (Thai), tr (Turkish), uk (Ukrainian), ur (Urdu), vi (Vietnamese), cy (Welsh).

Current online model catalog:
- Image: `gpt-image-2/text-to-image`, `gpt-image-2/text-to-image@pro`, `gpt-image-2/text-to-image@ext`, `gpt-image-2/image-to-image`, `gpt-image-2/image-to-image@pro`, `gpt-image-2/image-to-image@ext`, `Nano-Banana`, `Nano-Banana-2`, `Nano-Banana-Pro`, `flux-1.1-pro`, `flux-2/text-to-image`, `flux-2/image-to-image`, `flux-schnell/text-to-image`, `qwen-image-2.0`, `z-image`, `wan2.7-image/text-to-image`, `seedream-5.0-lite/text-to-image`, `seedream-5.0-lite/image-to-image`, `seedream-5.0-pro/text-to-image`, `seedream-5.0-pro/image-to-image`, `seedream-4.5/text-to-image`, `seedream-4.5/image-to-image`, `grok-imagine/text-to-image`, `grok-imagine/image-to-image`, `grok-imagine-quality/text-to-image`, `grok-imagine-quality/image-to-image`.
- Video: `seedance-2.0`, `seedance-2.0-mini`, `seedance-2.0-fast`, `veo-3.1/text-to-video`, `veo-3.1/image-to-video`, `veo-3.1-fast/text-to-video`, `veo-3.1-fast/image-to-video`, `grok-imagine/text-to-video`, `grok-imagine/image-to-video`, `grok-imagine-1.5/image-to-video`, `wan2.7-video/text-to-video`, `wan2.7-video/image-to-video`, `happyhorse-1.0`, `happyhorse-1.1/text-to-video`, `happyhorse-1.1/image-to-video`, `happyhorse-1.1/reference-to-video`, `kling-3.0-omni/text-to-video`, `kling-3.0-omni/image-to-video`, `kling-3.0-omni/reference-to-video`, `kling-3.0-turbo/text-to-video`, `kling-3.0-turbo/image-to-video`, `hailuo-2.3/text-to-video`, `hailuo-2.3/image-to-video`, `hailuo-2.3-fast/image-to-video`.
- Audio: `elevenlabs/text-to-dialogue`, `minimax-music-1.5`, `minimax-music-2.6`.

Some catalog models are reachable through the same endpoint while their full input fields are being finalized.

Example:
```json
{
  "model": "gpt-image-2/text-to-image",
  "input": { "prompt": "A red apple on a white table", "aspect_ratio": "1:1", "resolution": "1K" },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}
```

Production tip: for GPT Image 2 and other async models, prefer `callback.url` for terminal notifications in production. Use `GET /v1/tasks/{taskId}` polling for local debugging, low-volume jobs, or fallback reconciliation.

Seedance 2.0 mode note: first-frame image-to-video, first-last-frame image-to-video, and multimodal reference video generation (reference images, video, or audio) are mutually exclusive modes and should not be mixed. If strict first/last-frame matching matters, prefer the first-last-frame mode.

## MCP

HiAPI runs a hosted remote MCP (Model Context Protocol) server at `https://mcp.hiapi.ai/mcp`. Connect any MCP-compatible client (Claude Code, Cursor, and others) using your HiAPI API key as a Bearer token in the `Authorization` header — there is nothing to install or run locally. It exposes image and video tools (`generate_image`, `edit_image`, `generate_video`, `list_models`, `get_model_capabilities`, `get_pricing`) that all run on the Unified Async API (`POST /v1/tasks`). The server never stores the API key; it only forwards the `Authorization` header to `api.hiapi.ai`.

## Skills

HiAPI Skills install into Claude Code, Codex, or OpenClaw so you can generate images and videos by just asking — the agent fills in parameters, runs the generation, and hands back the result. Each skill runs on the Unified Async API with your `HIAPI_API_KEY` talking to `api.hiapi.ai` directly.

Install (Node.js 18+, after `export HIAPI_API_KEY=...`):
- `npx -y github:HiAPIAI/hiapi-gpt-image-2-skill -y` — GPT Image 2 (text-to-image and image-to-image)
- `npx -y github:HiAPIAI/hiapi-seedance-2-0-video-skill -y` — Seedance 2.0 video
- `npx -y github:HiAPIAI/hiapi-happyhorse-1-0-video-skill -y` — HappyHorse 1.0 video
- `npx -y github:HiAPIAI/hiapi-video-prompt-generator-skill -y` — video prompt director

Master repository and version catalog: `https://github.com/HiAPIAI/hiapi-skills` (skills.json). To build into your own product or backend instead, call `POST /v1/tasks` and `GET /v1/tasks/{taskId}` directly; model-specific input parameters are documented on each model detail page.

## Recent Updates

June 2026:
- HiAPI docs and model integrations now use the Unified Async Task API: create tasks with `POST /v1/tasks`, read results with `GET /v1/tasks/{taskId}`, and use `callback.url` for completion notifications.

## Async Task Pattern

Every model uses the same flow:

1. POST `/v1/tasks` → receive `{ "data": { "taskId": "tk-hiapi-..." } }`
2. GET `/v1/tasks/{taskId}` → poll until `status` is `success` or `fail` (interim states: `queued`, `handling`, `archiving`)
3. On `success`, read results from `data.output[].url`

Or set `callback.url` at creation to receive a terminal POST instead of polling. Use exponential backoff when polling.

## Error Handling

- `401` / `403` — Invalid or missing API key
- `429` — Rate limit exceeded, use exponential backoff
- `400` — Invalid parameters, check model name and required fields

## Pricing

Pricing varies by model. Check: https://www.hiapi.ai/en/pricing

## Links

- Unified Async API: https://www.hiapi.ai/docs/async-api/
- Model list: https://www.hiapi.ai/docs/models/
- Changelog: https://www.hiapi.ai/docs/changelog/
- Quickstart: https://www.hiapi.ai/docs/quickstart/