模型广场用于查看公开目录和价格，/v1/models 用于查询当前 API Key 可见的模型目录。配置任何客户端之前，都应该先查询自己的 Key，而不是只从网页复制模型名；实际可调用性仍需最小真实请求和使用日志确认。

第一步：准备 API Key

如果还没有 Key，先进入 https://console.zcloudapi.com 的「API 密钥」页面创建一条。然后把它放入当前终端。

macOS / Linux：

export ZHICLOUD_API_KEY="sk-你的-ZCloudAPI-Key"

Windows PowerShell：

$env:ZHICLOUD_API_KEY="sk-你的-ZCloudAPI-Key"

第二步：查询完整模型列表

macOS / Linux：

curl "https://api.zcloudapi.com/v1/models" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY"

Windows PowerShell：

curl.exe "https://api.zcloudapi.com/v1/models" `
  -H "Authorization: Bearer $env:ZHICLOUD_API_KEY"

响应结构示例（下面三个 YOUR_..._MODEL_ID 都是占位符，不表示当前已上架或已授权的模型）：

{
  "object": "list",
  "data": [
    { "id": "YOUR_TEXT_MODEL_ID", "object": "model" },
    { "id": "YOUR_CLAUDE_MODEL_ID", "object": "model" },
    { "id": "YOUR_IMAGE_MODEL_ID", "object": "model" }
  ]
}

从自己收到的 data[].id 中复制准确模型名。模型可见只说明它通过了当前 Key 的目录筛选；协议、余额和上游可用性仍需最小真实请求与使用日志确认。

第三步：只打印模型名

macOS / Linux 已安装 jq 时：

curl -s "https://api.zcloudapi.com/v1/models" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY" \
  | jq -r '.data[].id' \
  | sort

Windows PowerShell：

$headers = @{ Authorization = "Bearer $env:ZHICLOUD_API_KEY" }
$result = Invoke-RestMethod -Uri "https://api.zcloudapi.com/v1/models" -Headers $headers
$result.data.id | Sort-Object

把目标模型名直接从输出中复制，避免大小写、短横线和版本号输入错误。

第四步：按用途筛选

macOS / Linux 示例：

# GPT / Codex
curl -s "https://api.zcloudapi.com/v1/models" -H "Authorization: Bearer $ZHICLOUD_API_KEY" \
  | jq -r '.data[].id' | grep -E '^gpt-|codex'

# Claude
curl -s "https://api.zcloudapi.com/v1/models" -H "Authorization: Bearer $ZHICLOUD_API_KEY" \
  | jq -r '.data[].id' | grep '^claude-'

# 图片模型
curl -s "https://api.zcloudapi.com/v1/models" -H "Authorization: Bearer $ZHICLOUD_API_KEY" \
  | jq -r '.data[].id' | grep -E 'image|banana'

如果筛选结果为空，不代表平台完全没有该系列，而是当前 Key 的分组或模型限制没有开放它。

第五步：为模型选择正确协议

模型或用途	首选接口	对应教程
普通 GPT、国产文本模型	/v1/chat/completions	Chat Completions
Codex、GPT Agent	/v1/responses	Responses API
Claude 原生调用	/v1/messages	Claude Messages
GPT、Gemini、Grok 生图	/v1/images/generations	图片生成
GPT、Gemini、Grok 编辑	/v1/images/edits	图片生成

模型出现在列表中，只代表有权限，不代表它支持所有参数。工具调用、图片输入、推理参数和流式输出需要用目标模型单独测试。

第六步：核对价格

1. 打开 模型定价页面。
2. 使用搜索或服务商筛选找到目标模型。
3. 查看它是按输入/输出 Token 计费，还是按次计费。
4. 如果页面支持美元和人民币切换，先选择你实际使用的币种。
5. 用一次很小的请求验证，然后到「使用日志」核对 Token 和实际扣费。

不要根据模型名猜价格。相同系列的不同版本、图片尺寸和输出模型可能使用不同计费方式。

常见公开模型系列

下面只帮助你识别系列，实时结果仍以自己的 /v1/models 为准。

系列	常见模型示例
GPT	从本人 /v1/models 返回结果选择当前可见的 GPT 模型 ID
Claude	claude-sonnet-4-6、claude-opus-4-6、claude-opus-4-8
DeepSeek	deepseek-v3.2、deepseek-v4-flash、deepseek-v4-pro
GLM	glm-4.7、glm-5、glm-5.1、glm-5.2
Kimi	kimi-k2.5、kimi-k2.6、kimi-k2.7-code
Qwen	qwen3.5-plus、qwen3.6-plus、qwen3.7-max
图片	gpt-image-1k、gemini-3.1-flash-image、grok-imagine-image

实验性模型可能随时调整，不建议在未做回退方案时直接用于生产。

为什么模型广场和 /v1/models 不一致

• 模型广场展示平台公开目录和价格。
• /v1/models 会根据用户分组、Key 的模型限制和模型启用状态过滤。
• 管理员上架、下架或调整路由后，某条 Key 的结果会随权限变化。
• 同一账号的两条 Key 如果限制不同，也可能返回不同列表。

因此，生产程序启动前应检查目标模型；模型不存在时要停止请求或切换到经过测试的备用模型。

最后做一次真实验证

把下面的 YOUR_TEXT_MODEL_ID 占位符替换为刚刚由本人 Key 查询到、且支持 Chat Completions 的完整文本模型 ID：

curl "https://api.zcloudapi.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_TEXT_MODEL_ID",
    "messages": [{"role": "user", "content": "只回复 OK"}],
    "max_tokens": 16,
    "stream": false
  }'

返回 200、正文为 OK，并且使用日志出现记录，才算确认该模型不只是“可见”，而是当前确实可调用。