API 文档
山河云 API 兼容 OpenAI / Anthropic 协议,支持文本对话、流式输出、图片生成、视频生成等功能。
所有接口均使用 JSON 格式,认证方式为 Bearer Token。支持多种端点前缀以兼容不同客户端。
认证方式
所有 API 请求需要在 HTTP Header 中携带 API 密钥:
HTTP Header
Authorization: Bearer sk-your-api-key-here
对于 Claude 协议端点,也支持 x-api-key 头:
HTTP Header
x-api-key: sk-your-api-key-here
API 密钥可在 用户中心 获取,每个账户最多创建 5 个密钥。
Base URL
以下端点前缀均可使用,选择任意一个即可:
| 端点前缀 | 说明 |
|---|---|
https://api.0ki.cn/v1 | 标准 OpenAI 格式 |
https://api.0ki.cn/api/v1 | API 格式 |
https://api.0ki.cn/api/coding/paas/v4 | Coding PAAS 格式(推荐) |
https://api.0ki.cn/api/paas/v4 | PAAS 格式 |
https://api.0ki.cn/openapi/api/v1 | OpenAPI 格式 |
https://api.0ki.cn/api/anthropic | Anthropic Claude 专用 |
示例:调用 Chat Completions 接口 →
POST https://api.0ki.cn/api/coding/paas/v4/chat/completions
Chat Completions
POST
OpenAI 兼容的对话补全接口,支持主流大语言模型。
POST
/chat/completions
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 必填 | 模型名称,如 gpt-4o、claude-sonnet-4-20250514、deepseek-chat 等。传 auto 启用智能路由 |
| messages | array | 必填 | 消息列表,每条包含 role 和 content |
| stream | boolean | 可选 | 是否流式输出,默认 false |
| temperature | float | 可选 | 生成温度,0~2,默认 1。值越高输出越随机 |
| max_tokens | integer | 可选 | 最大生成 Token 数 |
| top_p | float | 可选 | 核采样概率,0~1,默认 1 |
| stop | string/array | 可选 | 停止序列,遇到时停止生成 |
| tools | array | 可选 | Function Calling 工具定义列表 |
| stream_options | object | 可选 | 流式选项,如 {"include_usage": true} 在最后一个 chunk 返回用量 |
Messages 格式
| 字段 | 类型 | 说明 |
|---|---|---|
| role | string | system、user、assistant、tool |
| content | string/array | 消息内容。字符串或支持多模态的数组格式(见下方图片输入) |
| tool_calls | array | assistant 消息中的工具调用结果 |
| tool_call_id | string | tool 角色消息的调用 ID |
请求示例
cURL
curl -X POST https://api.0ki.cn/api/coding/paas/v4/chat/completions \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [
{"role": "system", "content": "你是一个有帮助的助手"},
{"role": "user", "content": "你好,请介绍一下自己"}
],
"temperature": 0.7,
"max_tokens": 1024
}'响应示例
JSON
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1704067200,
"model": "gpt-4o",
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": "你好!我是一个AI助手..."
},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 20,
"completion_tokens": 50,
"total_tokens": 70
}
}
流式输出 (SSE)
POST
在 Chat Completions、Claude Messages、Responses API 中设置 "stream": true 即可启用流式输出。
流式输出使用 Server-Sent Events (SSE) 协议,响应头为
Content-Type: text/event-stream。
请求示例
cURL
curl -X POST https://api.0ki.cn/api/coding/paas/v4/chat/completions \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "写一首诗"}],
"stream": true,
"stream_options": {"include_usage": true}
}'流式响应格式
SSE Stream
// 每个 chunk 格式: data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"你"},"index":0}]} data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"好"},"index":0}]} // 最后一个 chunk(当 stream_options.include_usage=true): data: {"id":"chatcmpl-abc","choices":[{"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":10,"completion_tokens":20,"total_tokens":30}} // 结束标记: data: [DONE]
Claude Messages (Anthropic)
POST
Anthropic Claude 协议接口,原生支持 Claude 系列模型。
POST
/api/anthropic/v1/messages
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 必填 | Claude 模型名称,如 claude-sonnet-4-20250514 |
| messages | array | 必填 | 消息列表 |
| max_tokens | integer | 必填 | 最大输出 Token 数 |
| system | string/array | 可选 | 系统提示词 |
| stream | boolean | 可选 | 是否流式输出 |
| temperature | float | 可选 | 生成温度,0~1 |
| top_p | float | 可选 | 核采样概率 |
| tools | array | 可选 | 工具定义 |
| stop_sequences | array | 可选 | 自定义停止序列 |
请求示例
cURL
curl -X POST https://api.0ki.cn/api/anthropic/v1/messages \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-20250514",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, Claude!"}
]
}'
Responses API
POST
OpenAI Responses 格式接口,支持多轮对话和 Function Calling。
POST
/v1/responses
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 必填 | 模型名称 |
| input | string/array | 必填 | 输入内容,支持字符串或结构化数组 |
| instructions | string | 可选 | 系统指令(映射为 system 消息) |
| max_output_tokens | integer | 可选 | 最大输出 Token 数 |
| temperature | float | 可选 | 生成温度 |
| stream | boolean | 可选 | 是否流式输出 |
| tools | array | 可选 | 工具定义 |
| reasoning | object | 可选 | 推理配置,如 {"effort": "high"} |
| previous_response_id | string | 可选 | 上一轮响应 ID,用于多轮对话 |
请求示例
cURL
curl -X POST https://api.0ki.cn/v1/responses \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"input": "What is the capital of France?",
"instructions": "Answer concisely"
}'
Completions (文本补全)
POST
OpenAI 文本补全接口(非对话格式)。
POST
/v1/completions
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 必填 | 模型名称 |
| prompt | string | 必填 | 补全提示文本 |
| max_tokens | integer | 可选 | 最大生成 Token 数 |
| temperature | float | 可选 | 生成温度 |
| stream | boolean | 可选 | 是否流式输出 |
Embeddings (文本嵌入)
POST
POST
/v1/embeddings
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 必填 | 嵌入模型名称,如 text-embedding-3-small |
| input | string/array | 必填 | 需要嵌入的文本,支持字符串或字符串数组 |
图片生成
POST
根据文本描述生成图片,兼容 OpenAI 图片生成格式。
POST
/images/generations
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 必填 | 图片模型名称,如 Kwai-Kolors/Kolors、stable-diffusion-xl、flux-schnell 等 |
| prompt | string | 必填 | 图片描述文本 |
| negative_prompt | string | 可选 | 反向提示词,排除不想要的元素 |
| image_size | string | 可选 | 图片尺寸,格式 宽x高,如 1024x1024 |
| batch_size | integer | 可选 | 生成图片数量,1~4 |
| seed | integer | 可选 | 随机种子,固定种子可复现结果 |
| num_inference_steps | integer | 可选 | 推理步数,1~100,默认 20 |
| guidance_scale | float | 可选 | 引导系数,控制图片与提示词的匹配程度,默认 7.5 |
| image | string | 可选 | 参考图片,支持 URL 或 Base64(data:image/png;base64,...) |
推荐尺寸
| 模型 | 推荐尺寸 |
|---|---|
| Kolors | 1024x1024、960x1280、720x1440 |
| Qwen-Image | 1328x1328、1664x928、928x1664 |
| Stable Diffusion | 512x512、768x768 |
请求示例
cURL
curl -X POST https://api.0ki.cn/api/coding/paas/v4/images/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "Kwai-Kolors/Kolors",
"prompt": "a beautiful sunset over the ocean, vibrant colors",
"image_size": "1024x1024",
"batch_size": 1,
"num_inference_steps": 20,
"guidance_scale": 7.5
}'响应示例
JSON
{
"images": [
{ "url": "https://cdn.example.com/generated-image.png" }
],
"timings": { "inference": 3.2 },
"seed": 12345
}
生成的图片 URL 有效期为 1 小时,请及时下载保存。
视频生成(提交任务)
POST
提交视频生成任务,返回任务 ID。需配合 视频状态查询 接口轮询获取结果。
POST
/video/submit
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 必填 | 视频模型名称,如 Wan-AI/Wan2.2-T2V-A14B(文生视频)、Wan-AI/Wan2.2-I2V-A14B(图生视频) |
| prompt | string | 必填 | 视频描述文本 |
| negative_prompt | string | 可选 | 反向提示词 |
| image_size | string | 可选 | 视频尺寸,支持 1280x720、720x1280、960x960 |
| image | string | 可选 | 参考图片(图生视频模型必填),支持 URL 或 Base64 |
| seed | integer | 可选 | 随机种子 |
请求示例
cURL
# 文本生成视频 curl -X POST https://api.0ki.cn/api/coding/paas/v4/video/submit \ -H "Authorization: Bearer sk-your-api-key" \ -H "Content-Type: application/json" \ -d '{ "model": "Wan-AI/Wan2.2-T2V-A14B", "prompt": "A cat walking on a sunny beach, cinematic", "image_size": "1280x720" }'
响应示例
JSON
{
"requestId": "video-abc123def456"
}
视频状态查询
POST
查询视频生成任务的状态和结果。此接口不产生费用。
POST
/video/status
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| requestId | string | 必填 | 视频生成提交接口返回的任务 ID |
请求示例
cURL
curl -X POST https://api.0ki.cn/api/coding/paas/v4/video/status \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"requestId": "video-abc123def456"
}'响应示例
JSON - 生成中
{
"status": "InProgress",
"reason": ""
}JSON - 生成完成
{
"status": "Succeed",
"reason": "",
"results": {
"videos": [
{ "url": "https://cdn.example.com/video-abc123.mp4" }
],
"timings": { "inference": 45.2 },
"seed": 67890
}
}状态值说明
| 状态 | 说明 |
|---|---|
InQueue | 排队中 |
InProgress | 生成中 |
Succeed | 生成成功,可在 results 中获取视频链接 |
Failed | 生成失败,reason 中包含失败原因 |
视频生成结果有效期为 10 分钟,请及时下载保存。建议每 5~10 秒轮询一次状态。
模型列表
GET
获取可用模型列表,支持按类型过滤。无需认证。
GET
/v1/models
查询参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | string | 可选 | 模型类型:text、image、audio、video |
| sub_type | string | 可选 | 文本子类型(type=text 时):chat、embedding、reranker |
请求示例
cURL
# 获取所有模型 curl https://api.0ki.cn/v1/models # 仅获取图片模型 curl https://api.0ki.cn/v1/models?type=image # 仅获取聊天模型 curl https://api.0ki.cn/v1/models?type=text&sub_type=chat
响应示例
JSON
{
"object": "list",
"data": [
{ "id": "gpt-4o", "object": "model", "created": 1704067200, "owned_by": "openai" },
{ "id": "deepseek-chat", "object": "model", "created": 1704067200, "owned_by": "deepseek" }
]
}
错误码
错误响应格式
JSON
{
"error": {
"message": "错误描述",
"type": "error_type",
"code": "error_code"
}
}常见错误码
| HTTP 状态码 | 错误类型 | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求格式错误或参数缺失 |
| 401 | authentication_error | API 密钥无效或缺失 |
| 403 | model_not_allowed | 当前套餐不支持该模型 |
| 402 | insufficient_quota | 余额或请求次数不足 |
| 429 | rate_limit_error | 请求频率超限或并发数已满 |
| 500 | internal_error | 服务器内部错误 |
| 502 | upstream_error | 上游服务错误 |
| 503 | service_unavailable | 服务不可用或 Agent 离线 |
Python SDK 接入
使用 OpenAI 官方 Python SDK 快速接入,只需修改 base_url 和 api_key 即可。
安装 SDK
bash
pip install openai
对话示例
Python
from openai import OpenAI client = OpenAI( api_key="sk-your-api-key", base_url="https://api.0ki.cn/api/coding/paas/v4" ) # 非流式对话 response = client.chat.completions.create( model="gpt-4o", messages=[ {"role": "system", "content": "你是一个有帮助的助手"}, {"role": "user", "content": "你好,请介绍一下自己"} ], temperature=0.7 ) print(response.choices[0].message.content)
流式输出
Python
stream = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "写一首关于春天的诗"}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")图片生成
Python
response = client.images.generate(
model="Kwai-Kolors/Kolors",
prompt="a beautiful sunset over the ocean",
size="1024x1024",
n=1
)
print(response.data[0].url)
Node.js SDK 接入
安装 SDK
bash
npm install openai
对话示例
JavaScript
import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'sk-your-api-key', baseURL: 'https://api.0ki.cn/api/coding/paas/v4' }); // 非流式对话 const response = await client.chat.completions.create({ model: 'gpt-4o', messages: [ { role: 'system', content: '你是一个有帮助的助手' }, { role: 'user', content: '你好,请介绍一下自己' } ] }); console.log(response.choices[0].message.content);
流式输出
JavaScript
const stream = await client.chat.completions.create({ model: 'gpt-4o', messages: [{ role: 'user', content: '写一首关于春天的诗' }], stream: true }); for await (const chunk of stream) { process.stdout.write(chunk.choices[0]?.delta?.content || ''); }
cURL 快速测试
测试连通性
bash
# 查看模型列表 curl https://api.0ki.cn/v1/models # 健康检查 curl https://api.0ki.cn/health
Function Calling 示例
bash
curl -X POST https://api.0ki.cn/api/coding/paas/v4/chat/completions \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "北京今天天气怎么样?"}],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "获取指定城市的天气信息",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名称"}
},
"required": ["city"]
}
}
}]
}'
文件上传
POST
上传图片文件,获取可用于图片生成、图生视频等接口的 URL。
POST
/api/upload
| 说明 | 值 |
|---|---|
| Content-Type | multipart/form-data |
| 表单字段名 | file |
| 最大文件大小 | 20 MB |
| 支持格式 | PNG、JPG、JPEG、GIF、WebP |
请求示例
cURL
curl -X POST https://api.0ki.cn/api/upload \ -F "file=@/path/to/your/image.png"
响应示例
JSON
{
"url": "https://mcp.0ki.cn/uploads/abc123.png",
"filename": "abc123.png",
"size": 12345
}