MCP

HiAPI provides a hosted remote MCP (Model Context Protocol) server. After connecting, any MCP-compatible client — including Claude Code and Cursor — can call image, video, audio, and text generation tools. Media tools use the Unified Async API, while text tools use OpenAI-compatible text endpoints. No local deployment is required.

https://mcp.hiapi.ai/mcp

The server is stateless about credentials: it never stores your API key, it only forwards the Authorization header of each request to api.hiapi.ai.

Connect

Authentication uses your HiAPI API key as a Bearer token. Create one at Dashboard → API Keys.

claude mcp add --transport http hiapi https://mcp.hiapi.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

For clients configured via a JSON file (Cursor, Claude Desktop, and most others):

{
  "mcpServers": {
    "hiapi": {
      "type": "http",
      "url": "https://mcp.hiapi.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

DeepSeek Harness (DSH)‘s MCP client supports only static request headers, not OAuth, so connect it with an API key. First put the key in ~/.dsh/.env (Windows: C:\Users\<user>\.dsh\.env):

HIAPI_API_KEY=YOUR_API_KEY

Then append an insert entry to ~/.dsh/profiles/<profile>/cordis.patch.yml (the desktop app’s profile is usually desktop):

- insert:
    - id: mcp-hiapi
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: hiapi
        transport: streamable-http
        url: https://mcp.hiapi.ai/mcp
        headers:
          Authorization: !!js "`Bearer ${process.env.HIAPI_API_KEY}`"

It must be the insert form: a plain - id: line is silently skipped when the target doesn’t exist, so the plugin never loads. A key saved in the DSH settings UI never reaches process.env, so it has to go in .env. Restart DSH afterwards; the tools are named mcp__hiapi__…. If the profile can’t resolve the plugin, run dsh plugin --profile <profile> add @deepseek-ai/dsh-mcp-client first.

After connecting, the client discovers the available tools and invokes the corresponding capability, such as an image-generation or product-description request.

Tools

Tool	What it does	Default model
`generate_image`	Text-to-image, plus reference-image generation on models that support it	`gpt-image-2.5-sunburst/text-to-image`; `gpt-image-2.5-sunburst/image-to-image` with reference images
`edit_image`	Edit or transform an existing image (image-to-image)	`gpt-image-2.5-sunburst/image-to-image`
`generate_video`	Text-to-video and image-to-video	`seedance-2.5`: text-to-video, image-to-video, or reference-to-video, picked from the inputs
`generate_audio`	Dialogue speech, music, and other live audio models	`elevenlabs/text-to-dialogue`
`generate_text`	Generate text with any live text model; the catalog selects Chat or Responses	`gpt-6-astra`
`get_task_status`	Check an asynchronous image, video, or audio task by ID	—
`list_models`	List all live image, video, audio, and text models with capability summaries and published routes	—
`get_model_capabilities`	Per-model parameters: aspect ratios, resolutions, output formats, reference-image limits, durations	—
`get_model_schema`	Published parameter schema of any model: field names, types, required flags, allowed values, defaults, limits, endpoint type, and available routes (pass `route` to see that route’s fields); free and read-only	—
`get_pricing`	Live pricing metadata from `/api/pricing`	—
`estimate_price`	Estimate the USD cost from live public pricing without generating anything, using the same `model`, `route`, and `input` as `POST /v1/tasks`, including active promotions	—
`upload_file`	Upload an input image, audio, or video before generation and get a temporary HTTPS URL (deleted after 24 hours)	—
`get_balance`	Read the quota, usage, and total allowance of the API key in use	—

Image, video, and audio tools only submit a task through POST /v1/tasks and return its task_id right away; they never wait for the result, because MCP clients abandon a tool call after 30–60 seconds. Your AI then polls get_task_status with that ID (or you call the task detail endpoint): images and audio usually finish in 10–60 seconds, videos in 1–5 minutes. Don’t resubmit while a task is running — every submission is a new, separately charged task. To retry safely after a timeout or dropped connection, pass idempotency_key to generate_image, edit_image, generate_video, or generate_audio and reuse the same key on the retry: HiAPI then returns the original task instead of charging twice. Text models use the live catalog’s /v1/chat/completions or /v1/responses route. generate_text is synchronous: it returns the complete reply in one call (long or reasoning-heavy replies can take minutes) and reports a clear error when stream: true is requested. Every call is billed for the tokens it generates, even if the client times out or cancels, so don’t repeat a timed-out call with the same input.

Supported models match the live public catalog — see the model pages for exact parameters. Model-specific fields (for example Seedance reference videos, Wan ratio, FLUX safety_tolerance, or audio lyrics) go inside input, under the names the model page and get_model_schema use; the old params field still works but is no longer recommended. Models from a modality without a matching MCP tool are shown separately until support is added.

Same request as the REST API

The media generation tools take the same body as POST /v1/tasks: model, route, input, callback, storage, plus idempotency_key, so any REST example works as-is. Convenience top-level fields (prompt, aspect_ratio, …) are still accepted and are the same REST names.

route picks a route such as ext, beta, or pro. For gpt-image-2.5 pro, send model gpt-image-2.5-flare (or gpt-image-2.5-sunburst) with route: "pro"; the legacy @suffix spelling still works. get_model_schema lists the available routes and, given route, shows that route’s own fields; list_models prints the routes at the end of each row. See Model routes.

A model or route outside the public catalog (only open to some accounts) is no longer rejected by MCP — it is submitted verbatim and the backend decides, returning its own error when you lack access.

Alongside the text output, the generation tools and get_task_status return structuredContent equal to the REST data (generation tools add idempotent_replay).

Troubleshooting

Symptom	Fix
`401` / `403` from tools	Check the `Authorization: Bearer …` header in your client config
Balance or quota errors	Add funds at Dashboard → Billing
Result not ready yet	The task is still running — keep calling `get_task_status` with the same `task_id`; don’t submit the generation again
Client cannot connect	Verify the URL is exactly `https://mcp.hiapi.ai/mcp` and the transport is HTTP (streamable)

For model-specific workflows in an agent runtime, install Skills. For product or backend integration, call the Unified Async API directly.