# HiAPI

> HiAPI is an AI model gateway that provides unified access to image generation, video generation, and text models via OpenAI-compatible APIs.

Base URL: https://api.hiapi.ai
Docs: https://docs.hiapi.ai
OpenAPI spec: https://docs.hiapi.ai/hiapi.json

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

### Image Generation

Endpoint: POST https://api.hiapi.ai/v1/images/generations

Supported models:
- `qwen-image-2.0` — Alibaba Qwen Image 2.0, strong Chinese text rendering, low-cost 2K output
- `flux-1.1-pro` — Black Forest Labs FLUX 1.1 Pro, photorealistic product and portrait images
- `gpt-image-1.5` — OpenAI image generation with quality tiers: low, medium, high
- `gpt-image-2-beta` — OpenAI preview image generation model

Chat Completions image models:
- `gpt-image-2` — OpenAI chat-based image generation with aspect ratio control
- `Nano-Banana` — Google Nano Banana, fast generation and natural-language editing
- `Nano-Banana-2` — Google Nano Banana 2, supports 1K/2K output
- `Nano-Banana-Pro` — Google Nano Banana Pro, supports up to 4K output

Request:
```json
{
  "model": "qwen-image-2.0",
  "prompt": "your prompt here",
  "size": "2048*2048",
  "n": 1
}
```

Response: returns `data[0].url` with the generated image URL.

### Video Generation (Async)

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

Supported models:
- `kling-v3` — Cinematic text-to-video
- `seedance-1-0-pro` — Cost-effective text-to-video
- `seedance-1-5-pro` — 1080P cinematic text-to-video
- `seedance-2-0` — Text-to-video and image-to-video
- `wan2.7-t2v` — Text-to-video
- `wan2.7-i2v` — Image-to-video, requires `input_reference`

Request:
```json
{
  "model": "seedance-1-5-pro",
  "prompt": "your video prompt here",
  "seconds": "5",
  "size": "1920*1080"
}
```

Video generation is asynchronous. Poll for result:
```
GET https://api.hiapi.ai/v1/videos/{task_id}
```

When `status` is `succeeded`, the video URL is in `output.url`.

### Text / Chat Completions

Endpoint: POST https://api.hiapi.ai/v1/chat/completions

OpenAI-compatible. Supports text models available on the platform, plus chat-based image workflows such as `gpt-image-2` and Nano Banana models.

### Image Editing

Endpoint: POST https://api.hiapi.ai/v1/chat/completions

Use image-to-image-capable chat models for natural-language editing:
- `Nano-Banana`
- `Nano-Banana-2`
- `Nano-Banana-Pro`

Send the source image as `image_url` content and the edit instruction as text content.

## MCP Tools

HiAPI provides a Remote MCP endpoint for MCP-compatible AI tools. Users connect by adding the remote URL and their own HiAPI API key.

Remote MCP URL:
```
https://mcp.hiapi.ai/mcp
```

Authentication:
```
Authorization: Bearer YOUR_API_KEY
```

How to use MCP tools:
- Users do not manually fill tool parameter fields in the MCP connection settings.
- Users describe the task in natural language.
- The AI tool chooses the HiAPI MCP tool and fills the required parameters.
- If the user explicitly names a model, always pass that model in the `model` field.
- If the user does not name a model, call `list_models` or `get_model_capabilities` before choosing one.

Task mapping:
- Generate an image: use `generate_image` with `prompt`, and pass `model`, `aspect_ratio`, `size`, `quality`, `image_size`, or `n` when the user specifies them.
- Generate with reference images: use `generate_image` with image inputs only for `Nano-Banana`, `Nano-Banana-2`, or `Nano-Banana-Pro`. Reference images are optional for those models. Image inputs can be `image_url`, `image_data_uri`, `image_base64` plus `image_mime_type`, or `images`.
- Edit an image: use `edit_image` only with `Nano-Banana`, `Nano-Banana-2`, or `Nano-Banana-Pro`. `edit_image` requires at least one image input plus `prompt`; pass `model`, `aspect_ratio`, or `image_size` when specified. Image inputs can be `image_url`, `image_data_uri`, `image_base64` plus `image_mime_type`, `image_urls`, `image_data_uris`, or `images`.
- Generate a video: use `generate_video` only with video models. Pass `prompt`, `model`, `seconds`, `size`, `wait_for_completion`, and image inputs only when the selected model supports image-to-video.
- Browse models: use `list_models`.
- Check model parameters: use `get_model_capabilities`, optionally with `model`.
- Check pricing: use `get_pricing`, optionally with `model`.

Capability limits:
- Do not pass image inputs to text-to-image-only models such as `gpt-image-2`, `gpt-image-2-beta`, `qwen-image-2.0`, `flux-1.1-pro`, or `gpt-image-1.5`.
- Nano Banana reference images are optional. Without images, use text-to-image. With images, use reference-image generation or editing.
- Nano Banana models accept up to 14 reference images. Supported formats: JPG, PNG, WebP. Keep each image under 10MB. Uploaded images are compressed to a max side of 2048px before API calls.
- Uploaded local image video generation requires an image-to-video model. `wan2.7-i2v` requires an image. `seedance-2-0` can use an image optionally. Text-to-video-only models should not receive image inputs.

Local image uploads:
- Remote MCP cannot read local filesystem paths such as `/Users/.../image.png` or `C:\...`.
- If the user uploads an image in the AI tool, pass the image content as `image_data_uri` (`data:image/...;base64,...`) or as `image_base64` with `image_mime_type`.
- For multiple reference images, use `images` with items containing `url`, `data_uri`, `base64`, and `mime_type`.

Common field constraints:
- The public docs intentionally keep field names in a collapsed advanced reference to avoid repeating the natural-language request examples. For actual MCP calls, follow the detailed constraints below.
- `prompt` is required for image generation, image editing, and video generation.
- `model` is optional unless the user names a model. If the user names one, pass it exactly in `model`.
- `image_url`, `image_data_uri`, `image_base64`/`image_mime_type`, and `images` are conditional image-input fields. Use them only with Nano Banana reference generation/editing or image-to-video models.
- `edit_image` requires at least one image input and is limited to `Nano-Banana`, `Nano-Banana-2`, and `Nano-Banana-Pro`.
- `images` is only for Nano Banana models and accepts up to 14 reference images.
- `aspect_ratio` is for image models that support ratios. Check `get_model_capabilities` if unsure.
- `image_size` is for Nano Banana models; supported tiers differ by model.
- `quality` is only for selected image models such as `gpt-image-1.5`; do not send it to unsupported models.
- `n` is for selected Images API models; Chat Completions image models usually do not need it.
- `size` is model-dependent. Images API models and video models use different size sets.
- `seconds` is only for video models. Supported durations depend on the selected model.
- `input_reference` is for image-to-video. It is required by `wan2.7-i2v` and optional for `seedance-2-0`.
- `wait_for_completion` is optional for video generation. Default is to wait for completion; set `false` only when the user wants task creation without waiting.

Tool parameter schemas:
- `generate_image`
  - required: `prompt`
  - optional: `model`, `size`, `quality`, `aspect_ratio`, `image_size`, `n`, `image_url`, `image_data_uri`, `image_base64`, `image_mime_type`, `images`
  - use when the user asks to generate an image. If the user names a model, pass that model in `model`. Only pass image inputs to Nano Banana models.
- `edit_image`
  - required: `prompt` plus at least one image input
  - image inputs: `image_url`, `image_data_uri`, `image_base64` with `image_mime_type`, `image_urls`, `image_data_uris`, or `images`
  - optional: `model`, `aspect_ratio`, `image_size`, `mask_url`
  - use when the user asks to edit or transform an existing image. Supported image-to-image models: `Nano-Banana`, `Nano-Banana-2`, `Nano-Banana-Pro`.
- `generate_video`
  - required: `prompt`
  - optional: `model`, `seconds`, `size`, `input_reference`, `image_url`, `image_data_uri`, `image_base64`, `image_mime_type`, `wait_for_completion`
  - use `input_reference`, `image_data_uri`, or `image_base64` only for image-to-video models. `wan2.7-i2v` requires one; `seedance-2-0` accepts one optionally.
- `list_models`
  - required: none
  - optional: none
  - use before choosing a model if the user did not specify one.
- `get_model_capabilities`
  - required: none
  - optional: `model`
  - use to inspect supported sizes, aspect ratios, quality tiers, and workflows.
- `get_pricing`
  - required: none
  - optional: `model`
  - use to inspect pricing and multipliers.

Typical Remote MCP configuration shape:
```json
{
  "mcpServers": {
    "hiapi": {
      "url": "https://mcp.hiapi.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

AI agent setup procedure:
1. Configure the current MCP host with URL `https://mcp.hiapi.ai/mcp`.
2. Set transport type to Remote, HTTP, or Streamable HTTP if the client asks for one.
3. Add request header `Authorization: Bearer YOUR_API_KEY`.
4. Fully restart the MCP host after saving the config.
5. Call `list_models` or `get_model_capabilities` before choosing model-specific parameters.
6. Respect an explicit user-selected model. If the user did not select a model, choose one based on model capabilities.
7. Verify real image generation by calling `generate_image`, for example with `qwen-image-2.0`, `flux-1.1-pro`, `gpt-image-2`, or `Nano-Banana-Pro`.

## Skills

HiAPI also provides local agent Skills for users who want a fixed single-model workflow instead of the multi-model Remote MCP workflow.

Use Remote MCP when the user needs multiple models, image editing, pricing lookup, or model capability lookup. Use Skills when the user specifically wants an agent-local package for one model or one stable workflow.

Current Skills:
- GPT Image 2 Skill: generates with HiAPI `gpt-image-2` and saves the result locally.
- Seedance 2.0 Video Skill: generates text-to-video and image-to-video with HiAPI `seedance-2-0` and saves the result locally when downloadable.
- HappyHorse 1.0 Video Skill: generates videos with HiAPI `happyhorse-1-0` and saves the result locally.

Skill repositories:
```
https://github.com/HiAPIAI/hiapi-gpt-image-2-skill
https://github.com/HiAPIAI/hiapi-seedance-2-0-video-skill
https://github.com/HiAPIAI/hiapi-happyhorse-1-0-video-skill
```

Install into OpenClaw:
```bash
openclaw skills add https://github.com/HiAPIAI/hiapi-gpt-image-2-skill
openclaw skills add https://github.com/HiAPIAI/hiapi-seedance-2-0-video-skill
openclaw skills add https://github.com/HiAPIAI/hiapi-happyhorse-1-0-video-skill
```

Install into Codex:
```bash
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"

# GPT Image 2
rm -rf "${CODEX_HOME:-$HOME/.codex}/skills/hiapi-gpt-image-2"
git clone https://github.com/HiAPIAI/hiapi-gpt-image-2-skill.git "${CODEX_HOME:-$HOME/.codex}/skills/hiapi-gpt-image-2"

# Seedance 2.0 Video
rm -rf "${CODEX_HOME:-$HOME/.codex}/skills/hiapi-seedance-2-0-video"
git clone https://github.com/HiAPIAI/hiapi-seedance-2-0-video-skill.git "${CODEX_HOME:-$HOME/.codex}/skills/hiapi-seedance-2-0-video"

# HappyHorse 1.0 Video
rm -rf "${CODEX_HOME:-$HOME/.codex}/skills/hiapi-happyhorse-1-0-video"
git clone https://github.com/HiAPIAI/hiapi-happyhorse-1-0-video-skill.git "${CODEX_HOME:-$HOME/.codex}/skills/hiapi-happyhorse-1-0-video"
```

Run `npm test` inside the installed skill repository when available.

Configure the agent runtime:
```bash
export HIAPI_API_KEY="YOUR_API_KEY"
export HIAPI_BASE_URL="https://api.hiapi.ai"
```

After installation, restart the agent and ask it to use the matching skill. Examples:

> Use `$hiapi-gpt-image-2` to generate a 16:9 image of a sunset over the sea.
> Use `$hiapi-seedance-2-0-video` to animate this product photo into a 5-second cinematic clip.
> Use `$hiapi-happyhorse-1-0-video` to generate a 5-second 1080p wuxia rooftop scene.

Agent installation notes:
- https://github.com/HiAPIAI/hiapi-gpt-image-2-skill/blob/main/llms-install.md
- https://github.com/HiAPIAI/hiapi-seedance-2-0-video-skill/blob/main/llms-install.md
- https://github.com/HiAPIAI/hiapi-happyhorse-1-0-video-skill/blob/main/llms-install.md

## Async Task Pattern

Most image requests return synchronously. Video requests are async:

1. POST to create task → receive `{ "id": "task_id", "status": "pending" }`
2. GET `/v1/videos/{task_id}` → poll until `status` is `succeeded` or `failed`
3. Read video URL from `output.url`

Typical video generation takes 30–120 seconds. 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

- Full API Reference: https://docs.hiapi.ai/api-reference/
- Model list: https://docs.hiapi.ai/models/
- MCP guide: https://docs.hiapi.ai/for-ai/
- Skills guide: https://docs.hiapi.ai/skills/
- OpenAPI spec: https://docs.hiapi.ai/hiapi.json
- Quickstart: https://docs.hiapi.ai/quickstart/