Chat Completions 是兼容范围最广的文本接口，适合普通对话、问答、内容生成，以及大多数支持 OpenAI-compatible API 的客户端。

开始前准备三个值

配置	应该填写什么
Base URL	https://api.zcloudapi.com/v1
API Key	在个人控制台创建的 sk-... Key
Model	当前 Key 的 /v1/models 返回结果中的完整模型名

先把 Key 保存到当前终端。

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"

从本人 Key 返回的 data[].id 复制一个支持 Chat Completions 的完整文本模型 ID，替换下文每一处 YOUR_TEXT_MODEL_ID。这个字符串是占位符，不是平台模型名；模型可见后仍需用最小请求与使用日志确认可调用。

第二步：发送最小请求

macOS / Linux：

curl -i "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": "system", "content": "你是一个简洁的中文助手。"},
      {"role": "user", "content": "只回复：连接成功"}
    ],
    "max_tokens": 64,
    "stream": false
  }'

Windows PowerShell 建议先让 PowerShell 生成 JSON，避免引号转义错误：

$body = @{
  model = "YOUR_TEXT_MODEL_ID"
  messages = @(
    @{ role = "system"; content = "你是一个简洁的中文助手。" }
    @{ role = "user"; content = "只回复：连接成功" }
  )
  max_tokens = 64
  stream = $false
} | ConvertTo-Json -Depth 5

curl.exe -i "https://api.zcloudapi.com/v1/chat/completions" `
  -H "Authorization: Bearer $env:ZHICLOUD_API_KEY" `
  -H "Content-Type: application/json" `
  -d $body

成功时先看到 HTTP/2 200 或 HTTP/1.1 200，随后返回 JSON。

第三步：理解请求字段

字段	作用
model	要调用的公开模型名，必须与 /v1/models 完全一致
messages	对话历史，按顺序包含 system、user 和 assistant 消息
max_tokens	限制本次最多生成多少输出 Token
temperature	控制随机性；不是所有模型都支持，第一次测试可以不填
stream	false 一次性返回，true 使用 SSE 流式返回

第一次接入时只保留必要字段。基础请求成功后，再增加温度、工具调用、图片输入或其他高级参数。

第四步：读取响应

典型成功响应：

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "连接成功"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 4,
    "total_tokens": 28
  }
}

• 正文路径：choices[0].message.content
• 输入用量：usage.prompt_tokens
• 输出用量：usage.completion_tokens
• 总用量：usage.total_tokens

macOS / Linux 安装了 jq 时，可以只打印正文：

curl -s "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
  }' | jq -r '.choices[0].message.content'

第五步：使用 Python SDK

1. 新建项目目录并进入：

mkdir zhicloud-python-demo
cd zhicloud-python-demo
python -m venv .venv

2. 激活虚拟环境。

macOS / Linux：

source .venv/bin/activate

Windows PowerShell：

.venv\Scripts\Activate.ps1

3. 安装 SDK：

python -m pip install --upgrade openai

4. 新建 chat_demo.py：

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZHICLOUD_API_KEY"],
    base_url="https://api.zcloudapi.com/v1",
    timeout=60.0,
    max_retries=2,
)

response = client.chat.completions.create(
    model="YOUR_TEXT_MODEL_ID",
    messages=[
        {"role": "system", "content": "你是一个简洁的中文助手。"},
        {"role": "user", "content": "只回复：连接成功"},
    ],
    max_tokens=64,
)

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

5. 在已经设置 ZHICLOUD_API_KEY 的同一终端运行：

python chat_demo.py

第六步：使用 Node.js SDK

1. 新建目录并安装依赖：

mkdir zhicloud-node-demo
cd zhicloud-node-demo
npm init -y
npm install openai

2. 新建 chat-demo.mjs：

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.ZHICLOUD_API_KEY,
  baseURL: 'https://api.zcloudapi.com/v1',
  timeout: 60_000,
  maxRetries: 2,
})

const response = await client.chat.completions.create({
  model: 'YOUR_TEXT_MODEL_ID',
  messages: [
    { role: 'system', content: '你是一个简洁的中文助手。' },
    { role: 'user', content: '只回复：连接成功' },
  ],
  max_tokens: 64,
})

console.log(response.choices[0].message.content)
console.log(response.usage)

3. 运行：

node chat-demo.mjs

第七步：开启流式输出

curl 需要添加 -N，请求体设置 "stream": true：

curl -N "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": "写一段 100 字的产品介绍"}],
    "stream": true
  }'

服务会连续返回 data: {...} 数据块，以 data: [DONE] 结束。生产程序需要逐块解析 SSE，不能把每一行都当作完整 JSON。

第八步：核对日志和扣费

1. 打开 https://console.zcloudapi.com 的「使用日志」。
2. 按刚才的请求时间找到记录。
3. 检查模型、输入 Token、输出 Token 和扣费。
4. 如果程序返回成功但日志没有记录，确认 Base URL 是否确实是 https://api.zcloudapi.com/v1。

切换模型

只替换请求体中的 model，不要修改接口路径。例如：

{
  "model": "deepseek-v4-pro",
  "messages": [{ "role": "user", "content": "只回复 OK" }]
}

每次切换前都要确认模型存在于当前 Key 的 /v1/models，并先用 stream: false 做小请求。

常见错误

现象	处理步骤
401	重新复制 Key，检查 Authorization: Bearer 和环境变量
model not found	从 /v1/models 直接复制模型名
400 参数错误	删除温度、工具等可选字段，只保留最小请求
PowerShell JSON 错误	使用 ConvertTo-Json 生成请求体，不要直接复制 Bash 单引号写法
流式响应无法解析	先改回 stream: false，再检查 SSE 客户端实现
429 或 5xx	降低并发并有限重试，同时查看使用日志和服务状态