VarcolinkDocs
接入文档
五分钟接入。本页覆盖认证、接口地址与请求格式、计量规则、限制与错误码。接口的完整参数说明以控制台内文档为准。
1. 认证
所有请求通过密钥认证。密钥在控制台「密钥」页创建，格式为 sk- 开头的字符串，支持两种携带方式，任选其一：
Authorization: Bearer sk-xxxxxxxx
x-api-key: sk-xxxxxxxx密钥可随时在控制台停用或重建。停用立即生效，之后使用该密钥的请求返回 401。
2. 接口地址与请求格式
接口地址为 https://api.varcolink.cn。平台支持两种常见的请求格式，程序原本使用哪种就用哪种，不需要改动请求体结构：
| 格式 | 路径 | 说明 |
|---|---|---|
| 对话补全格式 | POST /v1/chat/completions | 以 messages 数组描述对话，支持工具调用与流式输出 |
| 消息格式 | POST /v1/messages | 以 messages 与 system 描述对话，支持工具调用、缓存与流式输出 |
请求体中 stream: true 时以服务器推送事件（SSE）逐段返回，否则一次性返回完整结果。模型通过 model 字段指定，可用模型与单价见控制台「价目」页。
curl https://api.varcolink.cn/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"<模型标识>","stream":true,"messages":[{"role":"user","content":"你好"}]}'3. 计量规则
每次调用结束后按四类分别计量并计入账单，控制台「用量」页可逐条查看：
| 计量项 | 含义 |
|---|---|
| 输入 | 本次请求送入模型的内容 |
| 输出 | 模型返回的内容 |
| 缓存写入 | 被标记为可复用并写入缓存的输入部分 |
| 缓存读取 | 命中缓存、以折扣价计量的输入部分 |
费用 = 各计量项数量 × 对应单价。单价按模型逐项公示，调整前至少提前 7 天在控制台公告。
4. 限制
- 密钥额度：可为每个密钥设置可用额度上限，用尽后返回
403。 - 可用范围：可限制密钥只能调用指定模型，或只能从指定 IP 段发起请求。
- 速率：按密钥限制每分钟请求数，超出返回
429，响应头给出建议的重试间隔。 - 请求体：单次请求体上限见控制台文档，超出返回
413。
专业版可申请提升速率与并发上限，团队版按需定制，发送邮件至 support@varcolink.cn 说明用途即可。
5. 错误码
| 状态码 | 含义 | 处理建议 |
|---|---|---|
400 | 请求格式错误 | 检查请求体字段与类型 |
401 | 密钥无效或已停用 | 在控制台核对密钥状态 |
403 | 余额不足或密钥额度用尽 | 预付服务费或调整密钥额度 |
429 | 超出速率限制 | 按响应头建议的间隔重试，或申请提升上限 |
5xx | 服务暂时不可用 | 短暂等待后重试；持续出现请联系支持并附上响应头中的请求编号 |
每个响应都带有请求编号（X-Request-Id），联系支持时附上它可以直接定位到那一次调用。