API REFERENCE · v1 · 2026-11-06
接入文档,
一条 base_url 跑通。
全站接口遵循 OpenAI 协议:把客户端里的 base_url 指向本站、api_key 换成本站密钥,现有 SDK 与工具无需改代码。对话、图片、视频三类模态共用同一套鉴权与计费。
https://api.pinocao.top/v1
01概览
本站是 OpenAI 兼容的 API 网关。请求统一经过 /v1 前缀,鉴权使用 Authorization: Bearer <密钥>,响应与错误格式与官方协议一致。
| 接口 | 方法 | 用途 |
|---|---|---|
/v1/models | GET | 列出已上架模型(公开,无需密钥) |
/v1/chat/completions | POST | 对话补全,支持流式与工具调用 |
/v1/images/generations | POST | 图片生成 |
/v1/videos | POST | 创建视频生成任务 |
/v1/videos | GET | 列出本人视频任务 |
/v1/videos/{task_id} | GET | 查询任务状态与结果 |
/v1/videos/{task_id}/content | GET | 下载生成的视频文件 |
同一模型可配置多个上游节点,请求失败会自动切换;实际命中的节点可在控制台调用日志中追溯。
02快速开始
三步完成首次调用:
- 创建密钥:登录 控制台 → 「密钥」页新建,密钥形如
sk-pc-…,仅在创建时完整显示一次。 - 指向 base_url:
https://api.pinocao.top/v1 - 发起请求:以下任选一种方式。
cURL
curl https://api.pinocao.top/v1/chat/completions \
-H "Authorization: Bearer sk-pc-你的密钥" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-pro",
"messages": [
{"role": "user", "content": "用一句话解释什么是 OpenAI 兼容协议"}
]
}'
Python · OpenAI SDK
from openai import OpenAI client = OpenAI( base_url="https://api.pinocao.top/v1", api_key="sk-pc-你的密钥", ) stream = client.chat.completions.create( model="deepseek-v4-pro", messages=[{"role": "user", "content": "你好"}], stream=True, ) for chunk in stream: delta = chunk.choices[0].delta.content or "" print(delta, end="", flush=True)
Node.js · OpenAI SDK
import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.pinocao.top/v1", apiKey: "sk-pc-你的密钥", }); const resp = await client.chat.completions.create({ model: "deepseek-v4-pro", messages: [{ role: "user", content: "你好" }], }); console.log(resp.choices[0].message.content);
03认证
所有业务接口都需要在请求头携带密钥:
Authorization: Bearer sk-pc-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Content-Type: application/json
- 密钥前缀:
sk-pc-,请勿与其它平台密钥混用。 - 仅显示一次:创建后只保留前缀用于识别,遗失只能重新创建。
- 独立策略:每个密钥可单独设置 RPM / TPM、每日消费上限与模型白名单。
- 停用即失效:密钥被停用或用户被停用后,请求立即返回 401。
04模型列表
该接口无需鉴权,返回当前已上架的模型与所属模态。模型随时上下架,建议在运行时拉取,不要硬编码。
curl https://api.pinocao.top/v1/models
正在读取模型清单…
| 模型 ID | 类型 | 能力标签 | 标记 |
|---|---|---|---|
| 加载中… | |||
能力标签按厂商与模态整理,用于快速选型;具体字段支持、图片尺寸与数量上限以上游模型文档为准。实时价格与计费单位见 模型目录,无需登录即可查看。
05对话补全
POST /v1/chat/completions,与官方接口一致。请求体除 model 会按上游映射外,其余字段原样透传。
| 参数 | 类型 | 说明 |
|---|---|---|
model 必填 | string | 对话模型 ID,见「模型列表」 |
messages 必填 | array | 消息数组,支持 system / user / assistant / tool |
stream | bool | 为 true 时以 SSE 增量返回,默认 false |
temperature | number | 采样温度,透传上游 |
max_tokens | int | 最大输出长度,影响预扣金额 |
tools / tool_choice | array / object | 工具调用,见下一节 |
response_format | object | 如需 JSON 输出可传 {"type":"json_object"},是否生效取决于上游模型 |
流式响应格式
服务端会为流式请求自动开启 stream_options.include_usage,因此最后一个数据块带 usage,可用于对账。
data: {"id":"chatcmpl-9f3a","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"你"},"finish_reason":null}]}
data: {"id":"chatcmpl-9f3a","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"好"},"finish_reason":null}]}
data: {"id":"chatcmpl-9f3a","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],
"usage":{"prompt_tokens":18,"completion_tokens":42,"total_tokens":60}}
data: [DONE]
06工具调用
使用标准 Function Calling:模型返回 tool_calls 后,由你的程序执行函数,再把结果以 role: "tool" 回传,继续下一轮对话。
{
"model": "deepseek-v4-pro",
"messages": [{"role": "user", "content": "北京今天天气怎么样"}],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的实时天气",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string", "description": "城市名"}},
"required": ["city"]
}
}
}],
"tool_choice": "auto"
}
{
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": null,
"tool_calls": [{
"id": "call_7f2a",
"type": "function",
"function": {"name": "get_weather", "arguments": "{\"city\":\"北京\"}"}
}]
},
"finish_reason": "tool_calls"
}]
}
是否支持工具调用取决于所选模型;不支持时上游会忽略该字段或报错,错误信息会原样返回。
07图片生成
POST /v1/images/generations,兼容 OpenAI Images 协议,按实际生成张数计费。
| 参数 | 类型 | 说明 |
|---|---|---|
model 必填 | string | 图片模型 ID |
prompt 必填 | string | 画面描述 |
n | int | 生成张数,1–10,默认 1;超出范围会自动收敛 |
size | string | 分辨率,如 1024x1024,透传上游 |
response_format | string | url 或 b64_json,取决于上游支持 |
curl https://api.pinocao.top/v1/images/generations \
-H "Authorization: Bearer sk-pc-你的密钥" \
-H "Content-Type: application/json" \
-d '{
"model": "nano-banana-2",
"prompt": "一只在竹林里喝茶的熊猫,水墨风格",
"n": 1,
"size": "1024x1024"
}'
{
"created": 1794533807,
"data": [
{"url": "https://.../result.png"}
]
}
08视频生成
视频为异步任务:创建后轮询状态,完成后下载产物。提交时按预估费用预扣,生成失败会自动原路退还。
创建任务
POST /v1/videos
| 参数 | 类型 | 说明 |
|---|---|---|
model 必填 | string | 视频模型 ID |
prompt 必填 | string | 画面描述 |
seconds | int | 时长 4–30 秒,默认 5;也可用 duration 传 |
resolution | string | 如 720p / 1080p,服务端会做归一化 |
# 1. 创建任务 curl https://api.pinocao.top/v1/videos \ -H "Authorization: Bearer sk-pc-你的密钥" \ -H "Content-Type: application/json" \ -d '{"model": "wan3.0-video", "prompt": "熊猫在竹林散步", "seconds": 5}' # 2. 查询状态(status: queued / in_progress / completed / failed) curl https://api.pinocao.top/v1/videos/vid_xxxxxxxxxxxx \ -H "Authorization: Bearer sk-pc-你的密钥" # 3. 完成后下载 MP4 curl https://api.pinocao.top/v1/videos/vid_xxxxxxxxxxxx/content \ -H "Authorization: Bearer sk-pc-你的密钥" -o video.mp4
{
"id": "vid_9c1f...",
"object": "video",
"model": "wan3.0-video",
"status": "queued",
"progress": 0,
"created_at": 1794533807,
"seconds": 5,
"resolution": "720p",
"estimated_cost_cny": 1.1319,
"has_content": false,
"error": null
}
轮询示例
import time, requests BASE = "https://api.pinocao.top/v1" HEAD = {"Authorization": "Bearer sk-pc-你的密钥"} task = requests.post(f"{BASE}/videos", headers=HEAD, json={ "model": "wan3.0-video", "prompt": "熊猫在竹林散步", "seconds": 5, }).json() while True: info = requests.get(f"{BASE}/videos/{task['id']}", headers=HEAD).json() if info["status"] in ("completed", "failed"): break time.sleep(5) if info["status"] == "completed": mp4 = requests.get(f"{BASE}/videos/{task['id']}/content", headers=HEAD) open("video.mp4", "wb").write(mp4.content)
- 并发上限:每个账号同时最多 2 个排队 / 生成中的任务,超出返回 429。
- 产物链接:上游链接会过期,服务端下载后会缓存;建议完成后尽快拉取。
- 查询列表:
GET /v1/videos?limit=20,limit 范围 1–100。
09错误码
错误响应与 OpenAI 一致:
{"error": {"message": "余额不足:本次预估 0.0120 元,当前余额 0.0040 元", "type": "insufficient_quota"}}
| 状态码 | type | 常见原因 |
|---|---|---|
| 400 | invalid_request_error | 请求体非 JSON、缺少 model / prompt、模态不匹配 |
| 401 | authentication_error | 未携带密钥、密钥无效或已撤销 |
| 402 | insufficient_quota | 余额不足:预估值大于余额,或结算时余额不足 |
| 403 | permission_error | 模型未开放 / 未定价,或密钥模型白名单不包含该模型 |
| 404 | invalid_request_error | 任务不存在或不属于当前账号 |
| 409 | invalid_request_error | 视频尚未生成完成就请求下载 |
| 429 | rate_limit_error | 超出 RPM / TPM / 每日消费上限 / 视频并发上限 |
| 502 / 503 | upstream_error | 上游异常或该模型暂无可用节点,可稍后重试 |
| 504 | upstream_error | 上游超时(单次请求总超时 300 秒) |
10计费与限额
- 余额校验:请求前按预估金额校验余额,不足直接返回 402,不会发起上游请求。
- 对话结算:按预估 tokens 预扣,请求结束后以真实
usage结算并退回差额。 - 图片结算:按实际生成张数结算。
- 视频结算:提交时按秒数 / 分辨率预扣,任务失败或提交失败会原路退还。
- 失败请求:上游失败不产生费用;预扣金额会退回余额,可在控制台流水核对。
- 密钥限额:可为每个密钥设置 RPM(每分钟请求数)、TPM(每分钟 token 数)、每日消费上限与模型白名单。
- 视频并发:每账号最多 2 个进行中的任务。
完整价目(按量计费)见 模型目录;余额与每笔流水都在控制台可查。
11客户端接入
凡是支持「自定义 OpenAI 接口地址」的工具,填入本站 base_url 与密钥即可使用。
| 工具 | 填写位置 | 值 |
|---|---|---|
| OpenAI SDK | base_url / api_key | https://api.pinocao.top/v1 |
| LangChain | base_url / api_key | 同上,使用 ChatOpenAI |
| Cherry Studio / NextChat | API 地址 + API Key | 同上,模型名从模型列表复制 |
| Dify / n8n | OpenAI 兼容模型供应商 | Base URL 填到 /v1 结尾 |
from langchain_openai import ChatOpenAI llm = ChatOpenAI( model="deepseek-v4-pro", api_key="sk-pc-你的密钥", base_url="https://api.pinocao.top/v1", ) print(llm.invoke("你好").content)
/chat/completions,因此填写时不要带多余路径,统一填 https://api.pinocao.top/v1。12常见问题
为什么一直返回 401?
确认密钥以 sk-pc- 开头、请求头是 Authorization: Bearer …、且密钥未被撤销。浏览器前端直接请求会暴露密钥,请放在服务端。
流式响应里读不到 usage?
平台已自动注入 stream_options.include_usage,usage 出现在最后一个数据块中,部分 SDK 需要显式读取。
模型名从哪里获取?
调用 GET /v1/models 或在本页「模型列表」查看,模型会随上架情况变化,请勿硬编码缓存过久。
支持 Anthropic / Gemini 原生协议吗?
目前统一为 OpenAI 兼容协议(/v1/chat/completions、/v1/images/generations、/v1/videos),暂不提供其它厂商的原生端点。
请求失败会扣钱吗?
不会。上游失败、超时、视频生成失败都会退还预扣金额;只有成功返回且产生 usage 的请求才会结算。
为什么某些参数没有生效?
参数会原样透传上游,是否支持取决于具体模型。若不支持,上游可能忽略或返回错误,错误信息会原样带回。