API 参考

4 个 chat 协议端点 + GET /v1/models 的请求 / 响应 schema 与 curl 示例,以及图像 / 视频 / Embedding / 知识库端点索引

本平台的全部对外端点都接受同一把 sk-gpushare-* API Key。本页详解 4 个 chat 协议端点与 GET /v1/models;图像 / 视频 / Embedding 与知识库端点在各自页面展开。

端点协议 / 用途详情
POST /v1/chat/completionsOpenAI Chat —— 通用最广,跨厂商本页
POST /v1/messagesAnthropic Messages —— Anthropic SDK 直连本页
POST /v1beta/models/{model}:generateContentGemini Native —— Google genai SDK 直连本页
POST /v1/responsesOpenAI Responses —— GPT-5.x 原生协议 + 内置工具本页
GET /v1/modelsOpenAI 模型发现(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

鉴权#

详见 鉴权。四种方式任选一种,按以下优先级回退:

  1. x-api-key: sk-gpushare-xxx header (推荐)
  2. x-goog-api-key: sk-gpushare-xxx header (Google genai SDK 默认 —— Gemini SDK 用户无需任何改造)
  3. ?key=sk-gpushare-xxx query
  4. Authorization: Bearer sk-gpushare-xxx header (OpenAI / Anthropic SDK 默认)

例外: GET /v1/models 只认 Authorization: Bearerx-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": {...}}
  ]
}
字段必填类型说明
modelstring模型 ID,见 模型列表
messagesarray对话历史,role ∈ {system, user, assistant, tool}
streambooltrue 启用 SSE 流式
max_tokensint生成 token 上限
temperaturefloat0-2
toolsarrayFunction tools 或内置工具 {type:"web_search"} / {type:"image_generation"}(约束见下)
tool_choicestring|objectauto / none / {type:"function","function":{...}}
stream_optionsobject流式时 {"include_usage": true} 让 trailing chunk 带 token 统计
response_formatobject{"type":"json_object"} 强制 JSON 输出

内置工具约束({type:"web_search"} / {type:"image_generation"}):

  • 这两个内置工具在本端点走 WebSocket V2 适配器,必须 stream: true —— 非流式直接 400 invalid_request(message: Tools `web_search` and `image_generation` require `stream: true` )
  • image_generation 仅 GPT-5.x(X1 渠道)支持,其他模型返 400 tool_not_supported
  • web_search 按模型 / 渠道支持情况门控,不支持的组合返 400 tool_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": [...]
}
字段必填类型说明
modelstring模型 ID
max_tokensintAnthropic 协议必填 (跟 OpenAI 不同)
messagesarray对话,role ∈ {user, assistant}
systemstring系统提示 (顶层字段,不放 messages)
streambool
toolsarrayAnthropic 工具格式 (name / description / input_schema)
tool_choiceobject{"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.x SKU 建议走 Gemini Native 端点;部分 gemini-* SKU 也接入了本端点。模型 × 端点的精确支持矩阵见 兼容矩阵
  • 模型存在但本端点没有可用渠道时返 503 no_channel_available
  • anthropic-version header 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-8X1
claude-sonnet-4-6X1
claude-haiku-4-5-20251001X1

调用其他模型时的错误语义:

  • 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
}
字段必填类型说明
modelstring支持的模型
inputarray | string建议始终用消息数组(见下)。GPT-5.x 的上游硬性要求 input 为数组,字符串形式会被上游拒绝
instructionsstring系统提示。顶层字段,不是 messages[0](跟 /v1/chat/completions 不同)。GPT-5.x 上游要求该字段存在,建议始终提供
streambooltrue 返回 SSE 事件流
max_output_tokensint生成上限(Responses API 用 _output_,不是 max_tokens)
reasoningobject{"effort": "low"|"medium"|"high"} 控制内部思考强度
temperature / top_p / frequency_penalty / presence_penaltyfloat标准采样参数
toolsarray工具类型
tool_choicestring | objectauto / none / {type:"function","name":"..."}
parallel_tool_callsbool默认 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-xxx
  • x-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/generations120s
POST /v1/videos/generations60s(仅提交;生成是异步的,不占请求时长)
POST /v1/embeddings30s

建议客户端 SDK timeout 设 ≥ 200 秒(长 reasoning turn / 工具调用 turn 可达数分钟,优先用流式);超长任务(视频)走异步轮询,见 图像 / 视频 / Embedding API

自动 failover 与重试#

上游 5xx / 连接失败时 gateway 自动换渠道重试,单个请求最多尝试 3 个渠道(同一请求偶尔耗时翻倍即此原因)。客户端收到 502 upstream_unreachable / 504 upstream_timeout 时可安全重试。