MCP

HiAPI 提供托管的远程 MCP（Model Context Protocol）服务。MCP 兼容客户端连接该服务后，即可调用图片、视频、音频和文本生成工具。媒体工具使用统一异步接口，文本工具使用 OpenAI 兼容文本接口，无需本地部署。

https://mcp.hiapi.ai/mcp

服务端不保存任何凭证：你的 API Key 只随每次请求的 Authorization 头转发给 api.hiapi.ai。

连接

鉴权使用你的 HiAPI API Key 作为 Bearer token。在控制台 → API Keys 创建。

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

适用于通过 JSON 文件配置的客户端（Cursor、Claude Desktop 等）：

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

DeepSeek Harness（DSH）的 MCP 客户端只支持静态请求头、不支持 OAuth，所以用 API Key 接入。先把 Key 写进 ~/.dsh/.env（Windows：C:\Users\<用户>\.dsh\.env）：

HIAPI_API_KEY=YOUR_API_KEY

再在 ~/.dsh/profiles/<profile>/cordis.patch.yml 末尾追加一条 insert 行（桌面版的 profile 通常是 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}`"

必须用 insert 形式：普通的 - id: 行在目标不存在时会被静默跳过，插件不会加载。在 DSH 设置界面里保存的 Key 不会进入 process.env，所以要写 .env。改完重启 DSH，工具名以 mcp__hiapi__ 开头。profile 里解析不到插件时，先运行 dsh plugin --profile <profile> add @deepseek-ai/dsh-mcp-client。

连接完成后，客户端会通过工具发现机制调用相应能力，例如提交图片生成或产品说明生成请求。

工具

工具	能力	默认模型
`generate_image`	文生图；支持参考图的模型可带参考图生成	`gpt-image-2.5-sunburst/text-to-image`；带参考图时用 `gpt-image-2.5-sunburst/image-to-image`
`edit_image`	编辑或改写现有图片（图生图）	`gpt-image-2.5-sunburst/image-to-image`
`generate_video`	文生视频和图生视频	`seedance-2.5`：按输入自动选文生视频、图生视频或参考生视频
`generate_audio`	对话语音、音乐和其他在线音频模型	`elevenlabs/text-to-dialogue`
`generate_text`	使用任意在线文本模型生成文本，自动选择 Chat 或 Responses 接口	`gpt-6-astra`
`get_task_status`	按任务 ID 查询异步图片、视频或音频任务	—
`list_models`	列出实时图片、视频、音频和文本模型及能力概要、可用线路	—
`get_model_capabilities`	模型参数明细：比例、分辨率、输出格式、参考图上限、时长	—
`get_model_schema`	任意模型的公开参数结构：字段名、类型、是否必填、可选值、默认值和限制，以及接口类型和可用线路（传 `route` 看该线路自己的字段）；免费只读	—
`get_pricing`	从 `/api/pricing` 获取实时价格	—
`estimate_price`	按实时公开价格估算美元成本，不实际生成；入参和 `POST /v1/tasks` 一样用 `model`、`route`、`input`，含进行中的活动价	—
`upload_file`	生成前上传输入图片、音频或视频，返回临时 HTTPS URL（24 小时后删除）	—
`get_balance`	读取当前 API Key 的额度、已用量和总额度	—

图片、视频和音频工具只通过 POST /v1/tasks 提交任务，立刻返回 task_id，不在调用里等结果（MCP 客户端的工具调用 30–60 秒就会放弃）。之后由 AI 用这个 ID 调 get_task_status 轮询（也可以直接调任务详情接口）：图片和音频通常 10–60 秒完成，视频 1–5 分钟。任务没完成时不要重新提交——每次提交都是一单新任务、单独计费。超时或连接断开后要安全重试，给 generate_image、edit_image、generate_video 或 generate_audio 传 idempotency_key，重试时复用同一个 key，HiAPI 会返回原来的任务，不会重复扣费。文本模型根据实时目录使用 /v1/chat/completions 或 /v1/responses；generate_text 是同步调用，一次返回完整回复（长回复或推理模型可能要几分钟），传 stream: true 会得到明确错误。每次调用都按实际生成的 token 计费，客户端超时或取消也一样，所以超时后不要用同样的输入再调一次。

支持的模型与实时公开目录一致——具体参数见模型页。模型专属字段（如 Seedance 参考视频、Wan 的 ratio、FLUX 的 safety_tolerance 和音频歌词）放进 input，字段名用模型页和 get_model_schema 里的名字；旧的 params 仍然能传，但不再推荐。暂时没有对应 MCP 工具的 modality 会单独列出。

和 REST 接口一样的请求

媒体生成工具的请求体和 POST /v1/tasks一致：model、route、input、callback、storage，外加 idempotency_key，REST 里的例子可以直接照搬。顶层的便捷字段（prompt、aspect_ratio 等）照样能用，名字和 REST 相同。

route 用来选线路，如 ext、beta、pro。gpt-image-2.5 的 pro 线路：model 传 gpt-image-2.5-flare（或 gpt-image-2.5-sunburst），配 route: "pro"；旧的 @后缀 写法仍然可用。get_model_schema 会列出可用线路，传入 route 时显示该线路自己的字段；list_models 在每行末尾显示线路。详见模型线路。

不在公开目录里的模型或线路（只对部分账号开放的），MCP 不再拦截，会原样提交、由后端判断权限；没有权限时返回后端自己的报错。

除了文本输出，生成工具和 get_task_status 还会返回 structuredContent，内容就是 REST 返回的 data（生成工具额外带 idempotent_replay）。

排障

现象	处理
工具返回 `401` / `403`	检查客户端配置里的 `Authorization: Bearer …` 头
余额或配额错误	到控制台 → 充值充值
结果还没好	任务仍在运行——继续用同一个 `task_id` 调 `get_task_status`，不要重新提交生成
客户端连不上	确认 URL 是 `https://mcp.hiapi.ai/mcp`，传输方式为 HTTP（streamable）

需要在 Agent 运行环境中按模型调用？请安装 Skills。需要集成到产品或后端？请直接调用统一异步接口。