PINOCAO TOKENS API DOCS

API REFERENCE · v1 · 2026-11-06

接入文档,
一条 base_url 跑通。

全站接口遵循 OpenAI 协议:把客户端里的 base_url 指向本站、api_key 换成本站密钥,现有 SDK 与工具无需改代码。对话、图片、视频三类模态共用同一套鉴权与计费。

BASE URL https://api.pinocao.top/v1
流式输出 · SSE 工具调用 · Function Calling 图片生成 视频异步任务 模型清单实时同步

01概览

本站是 OpenAI 兼容的 API 网关。请求统一经过 /v1 前缀,鉴权使用 Authorization: Bearer <密钥>,响应与错误格式与官方协议一致。

接口方法用途
/v1/modelsGET列出已上架模型(公开,无需密钥)
/v1/chat/completionsPOST对话补全,支持流式与工具调用
/v1/images/generationsPOST图片生成
/v1/videosPOST创建视频生成任务
/v1/videosGET列出本人视频任务
/v1/videos/{task_id}GET查询任务状态与结果
/v1/videos/{task_id}/contentGET下载生成的视频文件

同一模型可配置多个上游节点,请求失败会自动切换;实际命中的节点可在控制台调用日志中追溯。

02快速开始

三步完成首次调用:

  • 创建密钥:登录 控制台 → 「密钥」页新建,密钥形如 sk-pc-…,仅在创建时完整显示一次。
  • 指向 base_url:https://api.pinocao.top/v1
  • 发起请求:以下任选一种方式。

cURL

bashchat completions
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

python流式输出
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

javascriptchat completions
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认证

所有业务接口都需要在请求头携带密钥:

http请求头
Authorization: Bearer sk-pc-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
  • 密钥前缀:sk-pc-,请勿与其它平台密钥混用。
  • 仅显示一次:创建后只保留前缀用于识别,遗失只能重新创建。
  • 独立策略:每个密钥可单独设置 RPM / TPM、每日消费上限与模型白名单。
  • 停用即失效:密钥被停用或用户被停用后,请求立即返回 401。
密钥属于凭证,请只在服务端使用。前端代码、公开仓库、浏览器控制台都会造成泄露;一旦泄露请立即在控制台撤销。

04模型列表

该接口无需鉴权,返回当前已上架的模型与所属模态。模型随时上下架,建议在运行时拉取,不要硬编码。

bashGET /v1/models
curl https://api.pinocao.top/v1/models

正在读取模型清单…

模型 ID类型能力标签标记
加载中…

能力标签按厂商与模态整理,用于快速选型;具体字段支持、图片尺寸与数量上限以上游模型文档为准。实时价格与计费单位见 模型目录,无需登录即可查看。

05对话补全

POST /v1/chat/completions,与官方接口一致。请求体除 model 会按上游映射外,其余字段原样透传。

参数类型说明
model 必填string对话模型 ID,见「模型列表」
messages 必填array消息数组,支持 system / user / assistant / tool
streambool为 true 时以 SSE 增量返回,默认 false
temperaturenumber采样温度,透传上游
max_tokensint最大输出长度,影响预扣金额
tools / tool_choicearray / object工具调用,见下一节
response_formatobject如需 JSON 输出可传 {"type":"json_object"},是否生效取决于上游模型

流式响应格式

服务端会为流式请求自动开启 stream_options.include_usage,因此最后一个数据块带 usage,可用于对账。

ssetext/event-stream
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" 回传,继续下一轮对话。

json请求片段
{
  "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"
}
json模型返回
{
  "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画面描述
nint生成张数,1–10,默认 1;超出范围会自动收敛
sizestring分辨率,如 1024x1024,透传上游
response_formatstringurl 或 b64_json,取决于上游支持
bashPOST /v1/images/generations
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"
  }'
json响应示例
{
  "created": 1794533807,
  "data": [
    {"url": "https://.../result.png"}
  ]
}

08视频生成

视频为异步任务:创建后轮询状态,完成后下载产物。提交时按预估费用预扣,生成失败会自动原路退还。

创建任务

POST /v1/videos

参数类型说明
model 必填string视频模型 ID
prompt 必填string画面描述
secondsint时长 4–30 秒,默认 5;也可用 duration 传
resolutionstring如 720p / 1080p,服务端会做归一化
bash创建 + 轮询 + 下载
# 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
json任务对象
{
  "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
}

轮询示例

pythonpolling
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 一致:

json错误结构
{"error": {"message": "余额不足:本次预估 0.0120 元,当前余额 0.0040 元", "type": "insufficient_quota"}}
状态码type常见原因
400invalid_request_error请求体非 JSON、缺少 model / prompt、模态不匹配
401authentication_error未携带密钥、密钥无效或已撤销
402insufficient_quota余额不足:预估值大于余额,或结算时余额不足
403permission_error模型未开放 / 未定价,或密钥模型白名单不包含该模型
404invalid_request_error任务不存在或不属于当前账号
409invalid_request_error视频尚未生成完成就请求下载
429rate_limit_error超出 RPM / TPM / 每日消费上限 / 视频并发上限
502 / 503upstream_error上游异常或该模型暂无可用节点,可稍后重试
504upstream_error上游超时(单次请求总超时 300 秒)

10计费与限额

  • 余额校验:请求前按预估金额校验余额,不足直接返回 402,不会发起上游请求。
  • 对话结算:按预估 tokens 预扣,请求结束后以真实 usage 结算并退回差额。
  • 图片结算:按实际生成张数结算。
  • 视频结算:提交时按秒数 / 分辨率预扣,任务失败或提交失败会原路退还。
  • 失败请求:上游失败不产生费用;预扣金额会退回余额,可在控制台流水核对。
  • 密钥限额:可为每个密钥设置 RPM(每分钟请求数)、TPM(每分钟 token 数)、每日消费上限与模型白名单。
  • 视频并发:每账号最多 2 个进行中的任务。

完整价目(按量计费)见 模型目录;余额与每笔流水都在控制台可查。

11客户端接入

凡是支持「自定义 OpenAI 接口地址」的工具,填入本站 base_url 与密钥即可使用。

工具填写位置值
OpenAI SDKbase_url / api_keyhttps://api.pinocao.top/v1
LangChainbase_url / api_key同上,使用 ChatOpenAI
Cherry Studio / NextChatAPI 地址 + API Key同上,模型名从模型列表复制
Dify / n8nOpenAI 兼容模型供应商Base URL 填到 /v1 结尾
pythonLangChain
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)
注意:部分工具会在 base_url 后自动补 /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 的请求才会结算。

为什么某些参数没有生效?

参数会原样透传上游,是否支持取决于具体模型。若不支持,上游可能忽略或返回错误,错误信息会原样带回。