文档中心

皋智荟 API 接入文档

面向客户的接入说明，覆盖 API Key、模型 ID、OpenAI 兼容接口、Claude Messages、媒体任务、计费和常见错误。

查看完整接入指南进入客户后台
/api/v1统一基础地址
GZK客户 API Key
实时价格与模型同步
文档中心

接入前准备

客户需要先注册或登录客户中心，创建 API Key，并确认账户余额可用于模型调用。

  • 进入客户后台创建 API Key
  • 在模型中心复制可见模型 ID
  • 确认余额、日限额和月限额充足
文档中心

调用规则

客户只能看到和调用运营后台设置为显示的模型，模型价格和 Logo 会与运营后台保持一致。

  • OpenAI 兼容接口使用 Bearer Token
  • Claude Messages 使用 x-api-key
  • 隐藏或未定价模型无法调用
客户接入指南

从创建密钥到完成第一次调用

以下地址、鉴权方式和模型名称与当前皋智荟客户后台保持一致。运营后台隐藏的模型不会在客户侧展示，也不能被 API 调用。

1

注册/登录客户中心

进入客户后台，确认账户余额可用。

2

创建 API 密钥

在 API Keys 页面创建密钥，密钥只展示一次，请妥善保存。

3

选择可见模型

在模型中心复制模型 ID，例如 gpt-4.1、claude-opus-4-7、speech-2.8。

4

发起请求并查看账单

调用成功后，可在客户后台查看日志、Tokens、金额和余额流水。

基础地址

OpenAI 兼容
https://gaozhihui.com/api/v1
模型列表
/models 和 /models/{model}
Chat Completions
/chat/completions
Claude Messages
/messages
媒体任务
/media/generate 和 /media/status
调用前预检
/preflight

鉴权与计费

  • OpenAI 兼容接口使用 Authorization: Bearer GZK_xxxxxxxx。
  • Claude Messages 接口使用 x-api-key: GZK_xxxxxxxx。
  • 模型价格、Logo 和展示状态由运营后台统一控制，客户侧实时同步。
  • 调用前请确保余额充足，且 API Key 没有超出日/月限额。
  • 正式请求前可调用 /preflight 检查模型、余额、额度和中转节点。
  • 创建任务或非流式调用建议携带唯一的 Idempotency-Key，防止网络重试造成重复转发与扣费。
  • 第三方客户端可调用 GET /api/v1/models 自动拉取当前可用模型。
  • 模型列表会返回价格、计费单位、调用端点、能力标签、Logo、限额和中转来源标记。
  • 成功响应会携带 x-gaozhihui-balance、x-gaozhihui-available-balance 和 x-gaozhihui-balance-status，客户系统可据此提示充值。
  • 失败响应会返回 request_id、error.code 和 error.diagnostic，响应头会标记 x-retryable。

中转规则

  • 请求模型名称填写模型中心展示的公开 ID，皋智荟会自动映射到上游模型。
  • 运营后台隐藏的模型不会出现在客户前台，也无法通过 API 调用。
  • /api/v1/models 只返回已启用、已定价且未触发毛利保护的模型。
  • 每次调用都会生成请求 ID，客户后台可查看金额、Tokens、模型和时间。
  • 如遇上游异常，运营后台会在调用监控中显示失败原因与通道健康状态。
  • 错误诊断会说明失败原因、处理建议和是否适合自动重试，便于客户与运营快速定位。
  • /preflight 只展示中转节点可用性，不暴露真实上游地址或上游密钥。
  • 相同密钥、接口、幂等编号和参数会重放 24 小时内的原结果；参数不同会返回 409。

任务类模型

  • 图片、语音、视频等异步模型先调用 /media/generate 创建任务。
  • 返回 task_id 后使用 /media/status?task_id=... 查询结果。
  • 可选传入 callback_url，任务完成或失败后皋智荟会向该地址 POST 最终状态。
  • 回调地址生产环境必须使用 HTTPS，且不能指向本机、内网或云元数据地址。
  • 任务成功后按模型价格结算；失败任务会释放预占费用。
  • 建议前 30 秒每 2 秒查询一次，之后降低轮询频率。
  • 流式请求可使用幂等编号阻止重复扣费，但已结束的流不会再次重放。

OpenAI 兼容 cURL

curl https://gaozhihui.com/api/v1/chat/completions \
  -H "Authorization: Bearer GZK_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat_20260628_0001" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      { "role": "user", "content": "请用三句话介绍皋智荟" }
    ],
    "stream": false
  }'

Python SDK

from openai import OpenAI

client = OpenAI(
    api_key="GZK_xxxxxxxx",
    base_url="https://gaozhihui.com/api/v1"
)

response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[
        {"role": "user", "content": "请用三句话介绍皋智荟"}
    ],
    extra_headers={"Idempotency-Key": "chat_20260628_0001"}
)

print(response.choices[0].message.content)

Claude Messages

curl https://gaozhihui.com/api/v1/messages \
  -H "x-api-key: GZK_xxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: claude_20260628_0001" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "你好，请介绍你的能力" }
    ]
  }'

语音/媒体任务

curl https://gaozhihui.com/api/v1/media/generate \
  -H "Authorization: Bearer GZK_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: media_20260628_0001" \
  -d '{
    "model": "speech-2.8",
    "prompt": "欢迎使用皋智荟模型中转服务",
    "callback_url": "https://your-domain.com/webhooks/gaozhihui-media",
    "params": { "voice_id": "VOICE_ID" }
  }'

curl "https://gaozhihui.com/api/v1/media/status?task_id=TASK_ID" \
  -H "Authorization: Bearer GZK_xxxxxxxx"

调用前预检

# 快速检查模型、余额、权限和中转节点
curl "https://gaozhihui.com/api/v1/preflight?model=gpt-4.1" \
  -H "Authorization: Bearer GZK_xxxxxxxx"

# 正式请求前估算本次调用费用
curl https://gaozhihui.com/api/v1/preflight \
  -H "Authorization: Bearer GZK_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      { "role": "user", "content": "请检查本次调用是否可用" }
    ],
    "max_tokens": 1024
  }'

模型目录

curl https://gaozhihui.com/api/v1/models

# 每个模型会返回：
# metadata.pricing.display        客户可读价格
# metadata.endpoints.generate     本地调用端点
# metadata.endpoints.status       任务类模型状态查询端点
# metadata.relay.via_rugaoyun     是否经如皋云中转
# metadata.limits                 单客户限额

常见错误

所有网关错误都会携带请求编号和诊断建议。客户反馈问题时，请优先提供 request_id。

401API Key 无效、已撤销、过期，或来源 IP 不在白名单。

402账户余额不足，请先在客户后台提交充值。

403当前 API Key 没有该模型调用权限。

404模型被隐藏、名称填错，或该接口不支持这个模型。

409模型尚未完成定价，或幂等编号正在处理、已用于不同参数。

429请求过于频繁，或 API Key 的额度已用完。

503上游通道未配置、被停用，或没有可承接当前模型的通道。

继续浏览

相关页面

API 快速接入模型中心使用条款