快速开始

1. 准备环境变量

在控制台「我的密钥」点「新建密钥」。创建后会显示完整密钥，请复制保存；之后本人也能在密钥详情里再次查看。把下方占位值替换为自己的密钥，不要提交到代码仓库。

export MOSSHUB_API_BASE="https://api.mosshub.cn"
export MOSSHUB_API_KEY="替换为真实密钥"

配置完成后，后续示例会读取这两个变量。MOSSHUB_API_BASE 只写根地址，不要带 /v1，接口路径已写在示例里；根地址也显示在「我的密钥」页的接入配置里。

2. 查询可用模型

curl --fail-with-body "$MOSSHUB_API_BASE/v1/models" \
  -H "Authorization: Bearer $MOSSHUB_API_KEY"

返回的 data 数组只含这把密钥能调用的模型。选一个模型，把它的 id 填到下一步；不要把展示名称 display_name 当成 ID。下一步走 Chat Completions 接口：在控制台「模型」页打开模型详情，「接入」里列有 /v1/chat/completions 的模型才能这样调用。

3. 选择语言，发起对话

将示例里的 YOUR_MODEL_ID 替换为上一步选好的 ID。三种语言使用相同的请求参数，不会自动执行。

curl --fail-with-body "$MOSSHUB_API_BASE/v1/chat/completions" \
  -H "Authorization: Bearer $MOSSHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"你好"}],"stream":false}'

4. 读取结果

普通文本回答通常位于 choices[0].message.content。完整字段见文本对话。收到错误时先查看 HTTP 状态和 error.code，不要只凭状态码反复重试。

如果没有成功

• 401，invalid_api_key：密钥缺失、无效、已停用或已过期，见鉴权。
• 403，model_not_allowed：模型不在这把密钥的可用范围内；404，model_not_found：模型 ID 不存在。重新核对模型列表。
• 400 且提示模型不能通过这个接口调用：换一个支持 /v1/chat/completions 的模型。
• 402，insufficient_quota：密钥所花的预算已用完，在控制台申请追加额度。
• 其他错误：记下响应头 X-Request-Id，按错误处理排查。