仟川云
API 参考

API 调用文档

完整的 RESTful API 参考。兼容 OpenAI 协议，支持流式输出、向量计算、图像生成、语音转写。

获取 API Key浏览模型

概览

仟川云 API 提供统一的 RESTful 接口，兼容 OpenAI API 格式。通过一组 API Key 即可调用多种大模型，包括对话补全、向量、图像生成、语音转写等，全部支持 SSE 流式输出。

Base URL
http://127.0.0.1:8000/v1
格式
JSON + SSE
认证
Bearer Token

认证方式

所有 API 请求在 HTTP Header 中携带 API Key 进行认证。使用 Authorization 字段，格式为 Bearer <api-key>。

HTTP
Authorization: Bearer qc-sk-your-api-key-here
安全提示
  • · 请勿在客户端代码中硬编码 API Key
  • · 不要将 API Key 提交到公开仓库
  • · 泄露后请立即在控制台删除并重建

对话补全

POST/v1/chat/completions

创建对话补全请求。支持多轮对话、系统提示词、流式输出。最常用的 API 端点。

curl
curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer qc-sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-max",
    "messages": [
      {"role": "system", "content": "你是一个有帮助的助手。"},
      {"role": "user",   "content": "用一句话介绍仟川云。"}
    ],
    "temperature": 0.7,
    "stream": false
  }'
python
from openai import OpenAI

client = OpenAI(
    api_key="qc-sk-xxx",
    base_url="http://127.0.0.1:8000/v1",
)
resp = client.chat.completions.create(
    model="qwen-max",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

模型列表

GET/v1/models

列出当前账户可用的所有模型。

curl
curl http://127.0.0.1:8000/v1/models -H "Authorization: Bearer qc-sk-xxx"

流式输出

设置 "stream": true 启用 Server-Sent Events 流式传输。

curl
curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer qc-sk-xxx" \
  -H "Content-Type: application/json" \
  -N -d '{
    "model": "qwen-max",
    "messages": [{"role": "user", "content": "Hi"}],
    "stream": true
  }'

向量计算

POST/v1/embeddings
curl
curl http://127.0.0.1:8000/v1/embeddings \
  -H "Authorization: Bearer qc-sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-v2",
    "input": "你好世界"
  }'

图像生成

POST/v1/images/generations
curl
curl http://127.0.0.1:8000/v1/images/generations \
  -H "Authorization: Bearer qc-sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stable-diffusion-xl",
    "prompt": "a futuristic city at night",
    "n": 1,
    "size": "1024x1024"
  }'

语音转写

POST/v1/audio/transcriptions
curl
curl http://127.0.0.1:8000/v1/audio/transcriptions \
  -H "Authorization: Bearer qc-sk-xxx" \
  -F file=@audio.mp3 \
  -F model=whisper-1

错误处理

状态码含义说明
400Bad Request请求参数不合法
401UnauthorizedAPI Key 缺失或无效
403ForbiddenKey 无权限访问该模型
404Not Found端点或模型不存在
429Too Many Requests触发限流
500Internal Error服务器内部错误
502Bad Gateway上游渠道连接失败

限流策略

  • · 默认限流：60 RPM / Key，可在控制台调整
  • · 触发限流时返回 429
  • · 响应 Header 携带 X-RateLimit-Remaining
  • · 建议在客户端实现指数退避重试

SDK 接入

仟川云完全兼容 OpenAI SDK，只需改变 base URL 即可：

python
# Python
from openai import OpenAI
client = OpenAI(api_key="qc-sk-xxx", base_url="http://127.0.0.1:8000/v1")
node
// Node.js
import OpenAI from "openai"
const client = new OpenAI({ apiKey: "qc-sk-xxx", baseURL: "http://127.0.0.1:8000/v1" })

常见问题

如何获取 API Key？

登录控制台 → 控制面板 → API 管理 → 创建密钥。每个账号最多 5 个 Key。

是否支持自定义模型？

当前不支持。可联系商务申请私有部署，由我们部署到独立渠道并配置专属 Key。

调用失败如何排查？

查看响应 body 的 error.message，或登录控制台查看代理调用日志。