API 参考
4 个 chat 协议端点 + GET /v1/models 的请求 / 响应 schema 与 curl 示例,以及图像 / 视频 / Embedding / 知识库端点索引
本平台的全部对外端点都接受同一把 sk-gpushare-* API Key。本页详解 4 个 chat 协议端点与 GET /v1/models;图像 / 视频 / Embedding 与知识库端点在各自页面展开。
| 端点 | 协议 / 用途 | 详情 |
|---|---|---|
POST /v1/chat/completions | OpenAI Chat —— 通用最广,跨厂商 | 本页 |
POST /v1/messages | Anthropic Messages —— Anthropic SDK 直连 | 本页 |
POST /v1beta/models/{model}:generateContent | Gemini Native —— Google genai SDK 直连 | 本页 |
POST /v1/responses | OpenAI Responses —— GPT-5.x 原生协议 + 内置工具 | 本页 |
GET /v1/models | OpenAI 模型发现(SDK / 第三方客户端自动调用) | 本页 |
POST /v1/images/generations | 文生图 / 图生图(同步),按张计费 | 图像 / 视频 / Embedding API |
POST /v1/videos/generations(+ GET .../{id} 轮询 / GET 列表) | 文生视频 / 图生视频(异步任务),按秒计费 | 图像 / 视频 / Embedding API |
POST /v1/embeddings | 文本向量化(OpenAI 兼容) | 图像 / 视频 / Embedding API |
/api/v1/ext/wiki/*(8 条只读 REST)+ /mcp(MCP server) | 知识库检索 | 知识库 API & MCP |
Base URL: https://api.dflop.top
鉴权#
详见 鉴权。四种方式任选一种,按以下优先级回退:
x-api-key: sk-gpushare-xxxheader (推荐)x-goog-api-key: sk-gpushare-xxxheader (GooglegenaiSDK 默认 —— Gemini SDK 用户无需任何改造)?key=sk-gpushare-xxxqueryAuthorization: Bearer sk-gpushare-xxxheader (OpenAI / Anthropic SDK 默认)
例外:
GET /v1/models只认Authorization: Bearer和x-api-key两种 header,不支持?key=query。
POST /v1/chat/completions#
OpenAI Chat Completions 兼容端点。最通用,支持全部 chat 类模型(70+),完整列表见 模型列表 或 GET /v1/models。
图像 / 视频专属 SKU(Seedream / Seedance 等)不走本端点(调用返 503
no_channel_available),请走各自端点 —— 见 图像 / 视频 API。
请求#
{
"model": "claude-sonnet-4-6",
"messages": [
{"role": "system", "content": "You are helpful."},
{"role": "user", "content": "Hello"}
],
"stream": false,
"max_tokens": 1024,
"temperature": 0.7,
"tools": [
{"type": "function", "function": {...}}
]
}
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
model | ✓ | string | 模型 ID,见 模型列表 |
messages | ✓ | array | 对话历史,role ∈ {system, user, assistant, tool} |
stream | bool | true 启用 SSE 流式 | |
max_tokens | int | 生成 token 上限 | |
temperature | float | 0-2 | |
tools | array | Function tools 或内置工具 {type:"web_search"} / {type:"image_generation"}(约束见下) | |
tool_choice | string|object | auto / none / {type:"function","function":{...}} | |
stream_options | object | 流式时 {"include_usage": true} 让 trailing chunk 带 token 统计 | |
response_format | object | {"type":"json_object"} 强制 JSON 输出 |
内置工具约束(
{type:"web_search"}/{type:"image_generation"}):
- 这两个内置工具在本端点走 WebSocket V2 适配器,必须
stream: true—— 非流式直接 400invalid_request(message:Tools `web_search` and `image_generation` require `stream: true`)image_generation仅 GPT-5.x(X1 渠道)支持,其他模型返 400tool_not_supportedweb_search按模型 / 渠道支持情况门控,不支持的组合返 400tool_not_supported。各模型支持矩阵见 模型列表Function tools(
{type:"function",...})不受以上约束,流式 / 非流式均可。
响应 (非流式)#
{
"id": "chatcmpl-...",
"object": "chat.completion",
"created": 1715845200,
"model": "claude-sonnet-4-6",
"choices": [{
"index": 0,
"message": {"role": "assistant", "content": "Hello!"},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 5,
"total_tokens": 15
}
}
响应 (流式)#
stream: true 时返回 SSE 流,每条 data: 行为一个 chunk。详见 流式响应。
curl#
curl https://api.dflop.top/v1/chat/completions \
-H "Authorization: Bearer $PLATFORM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.4",
"messages": [{"role": "user", "content": "Hello"}]
}'
POST /v1/messages#
Anthropic Messages 兼容端点。
请求#
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": "You are helpful.",
"messages": [
{"role": "user", "content": "Hello"}
],
"stream": false,
"tools": [...]
}
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
model | ✓ | string | 模型 ID |
max_tokens | ✓ | int | Anthropic 协议必填 (跟 OpenAI 不同) |
messages | ✓ | array | 对话,role ∈ {user, assistant} |
system | string | 系统提示 (顶层字段,不放 messages) | |
stream | bool | ||
tools | array | Anthropic 工具格式 (name / description / input_schema) | |
tool_choice | object | {"type":"auto"|"any"|"tool", "name": "..."} |
响应 (非流式)#
{
"id": "msg_...",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-4-6",
"content": [
{"type": "text", "text": "Hello!"}
],
"stop_reason": "end_turn",
"usage": {"input_tokens": 10, "output_tokens": 5}
}
curl#
curl https://api.dflop.top/v1/messages \
-H "x-api-key: $PLATFORM_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello"}]
}'
限制#
- 主流
gemini-2.5/gemini-3.xSKU 建议走 Gemini Native 端点;部分gemini-*SKU 也接入了本端点。模型 × 端点的精确支持矩阵见 兼容矩阵 - 模型存在但本端点没有可用渠道时返 503
no_channel_available anthropic-versionheader SDK 自动注入;curl 直调时填2023-06-01
Gemini Native#
两条相关端点:
POST /v1beta/models/{model}:generateContent—— 非流式POST /v1beta/models/{model}:streamGenerateContent—— 流式
{model} 占位符在 URL 里直接写,如 /v1beta/models/gemini-2.5-pro:generateContent。
请求#
{
"contents": [
{"role": "user", "parts": [{"text": "Hello"}]}
],
"systemInstruction": {
"parts": [{"text": "You are helpful."}]
},
"generationConfig": {
"maxOutputTokens": 1024,
"temperature": 0.7
},
"tools": [...]
}
响应#
{
"candidates": [{
"content": {
"role": "model",
"parts": [{"text": "Hello!"}]
},
"finishReason": "STOP",
"index": 0
}],
"usageMetadata": {
"promptTokenCount": 10,
"candidatesTokenCount": 5,
"totalTokenCount": 15
}
}
curl#
curl "https://api.dflop.top/v1beta/models/gemini-2.5-pro:generateContent?key=$PLATFORM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"parts": [{"text": "Hello"}]}]
}'
限制#
- GPT-5.x 暂不支持该端点(模型存在但无渠道时返 503
no_channel_available),精确矩阵见 兼容矩阵
POST /v1/responses#
OpenAI Responses API 兼容端点 —— GPT-5.x 系列的原生协议。比 /v1/chat/completions 多两条原生工具:web_search(联网检索)和 image_generation(GPT-image-2 出图),响应里有完整 reasoning / output_text / 工具调用结构化字段。
支持的模型#
GPT-5 家族(原生)+ X1 渠道 Claude SKU,精确矩阵见 兼容矩阵:
| 模型 | 备注 |
|---|---|
gpt-5.4 | |
gpt-5.5 | 推荐 —— 支持 reasoning summary + 内置工具 |
claude-opus-4-6 / claude-opus-4-7 / claude-opus-4-8 | X1 |
claude-sonnet-4-6 | X1 |
claude-haiku-4-5-20251001 | X1 |
调用其他模型时的错误语义:
- model id 不在模型列表 → 400
model_not_found - 模型存在但本端点没有可用渠道 → 503
no_channel_available(改调/v1/chat/completions或该模型的 native 端点) model_not_allowed仅在你的 Key 配置了allowed_models白名单且不含该模型时出现
请求#
{
"model": "gpt-5.5",
"instructions": "You are concise.",
"input": [
{"role": "user", "content": "Say hello in 5 words."}
],
"stream": false,
"max_output_tokens": 1024,
"temperature": 1.0,
"top_p": 0.98,
"reasoning": {"effort": "medium"},
"tools": [
{"type": "web_search"},
{"type": "image_generation", "size": "1024x1024"},
{"type": "function", "name": "get_weather", "description": "...", "parameters": {...}}
],
"tool_choice": "auto",
"parallel_tool_calls": true
}
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
model | ✓ | string | 见 支持的模型 |
input | ✓ | array | string | 建议始终用消息数组(见下)。GPT-5.x 的上游硬性要求 input 为数组,字符串形式会被上游拒绝 |
instructions | string | 系统提示。顶层字段,不是 messages[0](跟 /v1/chat/completions 不同)。GPT-5.x 上游要求该字段存在,建议始终提供 | |
stream | bool | true 返回 SSE 事件流 | |
max_output_tokens | int | 生成上限(Responses API 用 _output_,不是 max_tokens) | |
reasoning | object | {"effort": "low"|"medium"|"high"} 控制内部思考强度 | |
temperature / top_p / frequency_penalty / presence_penalty | float | 标准采样参数 | |
tools | array | 见 工具类型 | |
tool_choice | string | object | auto / none / {type:"function","name":"..."} | |
parallel_tool_calls | bool | 默认 true |
input 数组形式 (多轮)#
"input": [
{"role": "user", "content": "What is 2+2?"},
{"role": "assistant", "content": "4"},
{"role": "user", "content": "What was my first question?"}
]
数组元素的 content 可用 string 简写;vision 必须用 content parts:
{"role": "user", "content": [
{"type": "input_text", "text": "Describe this image."},
{"type": "input_image", "image_url": "https://...", "detail": "auto"}
]}
注意:
input_image.image_url必须是公网可访问的 URL(上游会自己拉),CDN 缩略图 / 鉴权 URL 可能返upstream_error。
工具 (tools)#
// 1. 内置 web 检索 —— 模型自行决定是否调用,直接返回带答案的 output_text
{"type": "web_search"}
// 2. 内置出图 —— output 里返回 image_generation_call 项 (含 base64 result)
{"type": "image_generation", "size": "1024x1024"}
// 3. 用户自定义 function —— output 里返回 function_call 项,你执行后回带 function_call_output
{
"type": "function",
"name": "get_weather",
"description": "Get current weather",
"parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
}
响应 (非流式)#
{
"id": "resp_0a430185e6bd1abb016a1576c7bbb08198be6868b655d19349",
"object": "response",
"created_at": 1779791559,
"status": "completed",
"model": "gpt-5.5",
"instructions": "...",
"output": [
{
"type": "message",
"role": "assistant",
"content": [{"type": "output_text", "text": "Hello, hope you are well."}]
}
],
"reasoning": {"context": "current_turn", "effort": "medium", "summary": null},
"usage": {
"input_tokens": 25,
"input_tokens_details": {"cached_tokens": 0},
"output_tokens": 51,
"output_tokens_details": {"reasoning_tokens": 38},
"total_tokens": 76
}
}
output[] 数组按出现顺序排列,每项 type 之一:
type | 含义 |
|---|---|
message | 助手文本回复,文本在 content[].text |
reasoning | 内部推理 summary(可能为空) |
function_call | 模型决定调用你的 function,字段 call_id / name / arguments(JSON 字符串) |
image_generation_call | 内置 image_generation 工具执行结果,result 是 base64 PNG |
响应 (流式)#
stream: true 时返回 SSE,事件名带 response. 前缀。关键事件序列:
event: response.created // 整体 response 框架(usage=null)
event: response.in_progress
event: response.output_item.added // 第 N 个 output 项开始
event: response.output_text.delta // 文本增量,delta 字段是 chunk
event: response.output_text.done // 第 N 项文本完成
event: response.output_item.done // 第 N 项整体结束
event: response.completed // 全部完成,usage 已填充
每个 data: 都是单条 JSON 对象,自带 sequence_number 单调递增。详见 流式响应。
curl#
# 基础调用
curl https://api.dflop.top/v1/responses \
-H "Authorization: Bearer $PLATFORM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"instructions": "You are helpful.",
"input": [{"role": "user", "content": "Hello"}],
"max_output_tokens": 100
}'
# 联网检索
curl https://api.dflop.top/v1/responses \
-H "Authorization: Bearer $PLATFORM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"instructions": "You are helpful.",
"input": [{"role": "user", "content": "What is today date in Shanghai?"}],
"tools": [{"type": "web_search"}]
}'
# 流式
curl -N https://api.dflop.top/v1/responses \
-H "Authorization: Bearer $PLATFORM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"instructions": "You are helpful.",
"input": [{"role": "user", "content": "Count 1 to 3."}],
"stream": true
}'
限制#
- 多轮对话只能用
input数组自行维护历史。上游不持久化会话 item(store: false语义),previous_response_id不可用 —— 请每轮都把完整历史放进input数组 - 模型范围见 支持的模型。其他模型改调
/v1/chat/completions或各自的 native 端点(错误语义见上) - vision 受上游 URL 拉取限制 —— 部分 CDN 缩略图 / 鉴权 / 防盗链 URL 会失败。建议先把图传到自己的 R2 / S3 公开桶再传 URL
image_generation工具不强制流式 —— 本端点是 HTTP 透传,stream:false也能在响应的output[]里拿到image_generation_call.result(base64 PNG)。这跟/v1/chat/completions不同:那条端点的image_generation走专用 WebSocket 流式适配器,会强制stream:true并把图塞进delta.content的 markdown 里
GET /v1/models#
OpenAI 兼容的模型发现端点。OpenAI SDK 的 client.models.list() 与多数第三方客户端(Open WebUI / Cline / Continue 等)的自动模型发现调的就是它。
鉴权差异#
本端点只接受两种 header 鉴权,不支持 ?key= query(与其他端点的四级回退不同,Gemini 风格的 query 调用会 401):
Authorization: Bearer sk-gpushare-xxxx-api-key: sk-gpushare-xxx
响应#
{
"object": "list",
"data": [
{"id": "claude-sonnet-4-6", "object": "model", "created": 0, "owned_by": "anthropic"},
{"id": "gpt-5.5", "object": "model", "created": 0, "owned_by": "openai"}
]
}
- 返回 pricing 注册表全部条目,含图像 / 视频 / embedding 专属 SKU 与暂不可调用的占位 SKU —— 做模型菜单或脚本接入时建议按需过滤
- 如果你的 Key 配置了
allowed_models白名单,只返回白名单内的条目 - 另有免鉴权的
GET /api/v1/models/public,返回带价格 / 能力字段(含callable标志与endpoint_type)的完整注册表,适合做比价 / 筛选
curl#
curl https://api.dflop.top/v1/models \
-H "Authorization: Bearer $PLATFORM_API_KEY"
错误响应#
所有端点返回 HTTP 4xx/5xx 时,响应体为本协议官方错误 schema —— 不混用:
OpenAI 形状 (/v1/chat/completions、/v1/responses、/v1/embeddings)#
{"error": {"message": "...", "type": "...", "code": "..."}}
Anthropic Messages (/v1/messages)#
{"type": "error", "error": {"type": "...", "message": "..."}}
Gemini Native (/v1beta/...)#
{"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}
流式中的错误: 流式请求开流后(HTTP 200 已发出)再发生的上游错误无法更改状态码 —— 表现为流提前终止或 SSE 错误帧,客户端需对"流未正常收尾"做兜底。详见 错误码。
最高频错误是余额耗尽:HTTP 402,OpenAI 形状 code: "quota_exceeded" / type: "insufficient_quota"(Anthropic 形状 type: "billing_error",Gemini 形状 status: "RESOURCE_EXHAUSTED")。完整错误码真值表见 错误码。
限制与超时#
速率限制#
当前未做硬性 QPS 限制。429 rate_limit_exceeded 为上游限流透传,按指数退避重试即可。
计费与余额#
按账户统一余额(美元钱包)扣费,所有 API Key 共享同一余额 —— Key 本身没有独立预算池,余额耗尽时所有 Key 同时返 402(「新建 Key」不能解决额度问题)。注册即送 $0.30 体验额度;充值入口在主站 dflop.top/dashboard/billing(与 model.dflop.top 同账号)。详见 鉴权。
超时#
| 端点 | 上游超时 |
|---|---|
chat 四协议端点(/v1/chat/completions、/v1/messages、/v1/responses、/v1beta/...) | 180s 总时长(流式同样受 180s 总上限约束 —— 流式只是更早拿到首 token,不是不限时) |
POST /v1/images/generations | 120s |
POST /v1/videos/generations | 60s(仅提交;生成是异步的,不占请求时长) |
POST /v1/embeddings | 30s |
建议客户端 SDK timeout 设 ≥ 200 秒(长 reasoning turn / 工具调用 turn 可达数分钟,优先用流式);超长任务(视频)走异步轮询,见 图像 / 视频 / Embedding API。
自动 failover 与重试#
上游 5xx / 连接失败时 gateway 自动换渠道重试,单个请求最多尝试 3 个渠道(同一请求偶尔耗时翻倍即此原因)。客户端收到 502 upstream_unreachable / 504 upstream_timeout 时可安全重试。