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/v1API 格式
https://api.0ki.cn/api/coding/paas/v4Coding PAAS 格式(推荐)
https://api.0ki.cn/api/paas/v4PAAS 格式
https://api.0ki.cn/openapi/api/v1OpenAPI 格式
https://api.0ki.cn/api/anthropicAnthropic Claude 专用
示例:调用 Chat Completions 接口 → POST https://api.0ki.cn/api/coding/paas/v4/chat/completions
Chat Completions POST

OpenAI 兼容的对话补全接口,支持主流大语言模型。

POST /chat/completions

请求参数

参数类型必填说明
modelstring必填模型名称,如 gpt-4oclaude-sonnet-4-20250514deepseek-chat 等。传 auto 启用智能路由
messagesarray必填消息列表,每条包含 rolecontent
streamboolean可选是否流式输出,默认 false
temperaturefloat可选生成温度,0~2,默认 1。值越高输出越随机
max_tokensinteger可选最大生成 Token 数
top_pfloat可选核采样概率,0~1,默认 1
stopstring/array可选停止序列,遇到时停止生成
toolsarray可选Function Calling 工具定义列表
stream_optionsobject可选流式选项,如 {"include_usage": true} 在最后一个 chunk 返回用量

Messages 格式

字段类型说明
rolestringsystemuserassistanttool
contentstring/array消息内容。字符串或支持多模态的数组格式(见下方图片输入)
tool_callsarrayassistant 消息中的工具调用结果
tool_call_idstringtool 角色消息的调用 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

请求参数

参数类型必填说明
modelstring必填Claude 模型名称,如 claude-sonnet-4-20250514
messagesarray必填消息列表
max_tokensinteger必填最大输出 Token 数
systemstring/array可选系统提示词
streamboolean可选是否流式输出
temperaturefloat可选生成温度,0~1
top_pfloat可选核采样概率
toolsarray可选工具定义
stop_sequencesarray可选自定义停止序列

请求示例

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

请求参数

参数类型必填说明
modelstring必填模型名称
inputstring/array必填输入内容,支持字符串或结构化数组
instructionsstring可选系统指令(映射为 system 消息)
max_output_tokensinteger可选最大输出 Token 数
temperaturefloat可选生成温度
streamboolean可选是否流式输出
toolsarray可选工具定义
reasoningobject可选推理配置,如 {"effort": "high"}
previous_response_idstring可选上一轮响应 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
参数类型必填说明
modelstring必填模型名称
promptstring必填补全提示文本
max_tokensinteger可选最大生成 Token 数
temperaturefloat可选生成温度
streamboolean可选是否流式输出
Embeddings (文本嵌入) POST
POST /v1/embeddings
参数类型必填说明
modelstring必填嵌入模型名称,如 text-embedding-3-small
inputstring/array必填需要嵌入的文本,支持字符串或字符串数组
图片生成 POST

根据文本描述生成图片,兼容 OpenAI 图片生成格式。

POST /images/generations

请求参数

参数类型必填说明
modelstring必填图片模型名称,如 Kwai-Kolors/Kolorsstable-diffusion-xlflux-schnell
promptstring必填图片描述文本
negative_promptstring可选反向提示词,排除不想要的元素
image_sizestring可选图片尺寸,格式 宽x高,如 1024x1024
batch_sizeinteger可选生成图片数量,1~4
seedinteger可选随机种子,固定种子可复现结果
num_inference_stepsinteger可选推理步数,1~100,默认 20
guidance_scalefloat可选引导系数,控制图片与提示词的匹配程度,默认 7.5
imagestring可选参考图片,支持 URL 或 Base64(data:image/png;base64,...

推荐尺寸

模型推荐尺寸
Kolors1024x1024960x1280720x1440
Qwen-Image1328x13281664x928928x1664
Stable Diffusion512x512768x768

请求示例

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

请求参数

参数类型必填说明
modelstring必填视频模型名称,如 Wan-AI/Wan2.2-T2V-A14B(文生视频)、Wan-AI/Wan2.2-I2V-A14B(图生视频)
promptstring必填视频描述文本
negative_promptstring可选反向提示词
image_sizestring可选视频尺寸,支持 1280x720720x1280960x960
imagestring可选参考图片(图生视频模型必填),支持 URL 或 Base64
seedinteger可选随机种子

请求示例

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

请求参数

参数类型必填说明
requestIdstring必填视频生成提交接口返回的任务 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

查询参数

参数类型必填说明
typestring可选模型类型:textimageaudiovideo
sub_typestring可选文本子类型(type=text 时):chatembeddingreranker

请求示例

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 状态码错误类型说明
400invalid_request_error请求格式错误或参数缺失
401authentication_errorAPI 密钥无效或缺失
403model_not_allowed当前套餐不支持该模型
402insufficient_quota余额或请求次数不足
429rate_limit_error请求频率超限或并发数已满
500internal_error服务器内部错误
502upstream_error上游服务错误
503service_unavailable服务不可用或 Agent 离线
Python SDK 接入

使用 OpenAI 官方 Python SDK 快速接入,只需修改 base_urlapi_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-Typemultipart/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
}