认证方式
neospark API 支持多种认证方式，覆盖大多数主流 SDK 和开发场景。
1. Bearer Token（最常用）
适用于绝大多数公开 API 接口：
Authorization: Bearer YOUR_API_KEY覆盖 /v1/*、/v1beta/*、/mj/*、/kling/v1/*、/dashboard/billing/*
2. Claude 兼容头
用于 POST /v1/messages 等 Claude 原生格式端点：
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-013. Gemini 兼容头
用于 GET /v1beta/models 和 POST /v1beta/models/{model}:{action}：
x-goog-api-key: YOUR_API_KEY也兼容 ?key=YOUR_API_KEY 查询参数方式
4. 用户登录态
用于 /api/user/*、后台管理和部分前端仪表盘接口。典型特征：
- 需要先在浏览器中完成登录，并在请求中携带有效登录态。
- 失败时很多接口仍返回 HTTP
200，但success为false。
5. OAuth 浏览器流程
用于浏览器登录态场景：
GET/api/oauth/state— 生成 state 值
GET/api/oauth/{provider}— OAuth 回调路由
支持 provider: github、discord、oidc、linuxdo
6. 认证失败时的常见返回
公开 API 接口错误格式：
{
"error": {
"message": "Invalid API key provided",
"type": "invalid_request_error",
"param": "",
"code": "invalid_api_key"
}
}/api/* 路由错误格式：
{
"success": false,
"message": "无效的令牌"
}文字系列
支持 OpenAI Chat Completions、Responses、Claude Messages、Gemini 原生格式，覆盖聊天、Agent、长文本生成、多模态输入、工具调用、结构化输出等场景。
接口清单
| Method | Path | 说明 |
|---|---|---|
| POST | /v1/chat/completions | 通用对话接口（默认流式），OpenAI Chat Completions 兼容格式 |
| POST | /v1/chat/completions | 通用对话接口（默认非流式），同一路由的非流式写法 |
| POST | /v1/completions | 文本补全接口，Legacy Completions 兼容格式 |
| POST | /v1/messages | Claude 消息接口，Anthropic Messages 原生协议 |
| POST | /v1/responses | OpenAI 多模态响应接口，Responses API |
| POST | /v1/responses/compact | 上下文压缩 |
| GET | /v1/realtime | Realtime 接口，OpenAI Realtime 兼容 WebSocket |
| GET | /v1/models | 模型列表，OpenAI/Claude/Gemini 兼容 |
| GET | /v1/models/{model} | 单模型查询 |
| GET | /v1beta/models | Gemini 原生模型列表 |
| POST | /v1beta/models/{model}:{action} | Gemini 原生推理与图像/视频相关动作 |
| GET | /v1beta/openai/models | Gemini 兼容模型列表 |
| POST | /pg/chat/completions | Playground 调试路由，使用登录态而非 API Key |
通用错误码
| 状态码 | 说明 |
|---|---|
| 400 | 请求参数错误，例如模型名不存在、消息结构无效、工具定义不合法 |
| 401 | API Key 缺失、无效或过期 |
| 402 | 额度不足 |
| 413 | 请求体过大 |
| 429 | 请求频率超限 |
| 500 | 服务端内部错误 |
| 503 | 上游不可用或系统临时过载 |
提示：如果接口页里标记了"可选"参数，不代表所有模型都支持该字段。最终是否透传、是否生效，仍取决于实际分发到的渠道能力。
通用对话接口（Chat Completions）
POST/v1/chat/completions
描述OpenAI Chat Completions 兼容格式，支持流式与非流式返回
支持OpenAI、Claude、Gemini、DeepSeek、Qwen 等上游模型
请求参数
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| model | string | 是 | 模型名称，可通过模型列表查询可用模型 |
| messages | array | 是 | 对话消息数组，角色：system、user、assistant、tool |
| stream | boolean | 否 | true 为 SSE 流式返回；默认 false 非流式 |
| max_tokens | integer | 否 | 最大生成 token 数 |
| max_completion_tokens | integer | 否 | 最大补全 token 数，含推理 token |
| temperature | number | 否 | 采样温度 0~2，较低值更稳定 |
| top_p | number | 否 | 核采样参数 0~1 |
| tools | array | 否 | 函数调用工具列表，兼容 OpenAI tools 格式 |
| tool_choice | string/object | 否 | 工具调用控制：auto、none、required |
| response_format | object | 否 | 输出格式：json_object 或 json_schema |
| reasoning_effort | string | 否 | 推理强度：low、medium、high、xhigh |
| stream_options.include_usage | boolean | 否 | 流式最后一条携带 token 用量统计 |
OpenAI 多模态响应接口（Responses）
POST/v1/responses
POST/v1/responses/compact— 上下文压缩
描述适合工具调用、结构化输出和上下文续接
Claude 原生消息接口
POST/v1/messages
描述保留 Anthropic Messages 原生协议
认证x-api-key + anthropic-version: 2023-06-01
Gemini 原生格式
GET/v1beta/models— 模型列表
POST/v1beta/models/{'{model}'}:{'{action}'}— 推理与图像/视频动作
认证x-goog-api-key 或 ?key=YOUR_API_KEY
模型列表
GET/v1/models— OpenAI/Claude/Gemini 兼容模型列表
GET/v1/models/{'{model}'}— 单模型查询
GET/v1beta/openai/models— Gemini 兼容模型列表
图像系列
统一图像生成入口，支持 OpenAI Images 兼容、gpt-image-2、Gemini 生图、Midjourney 以及豆包 Seedream 等模型。
POST/v1/images/generations— 统一图像生成入口
POST/v1/images/edits— 图像编辑（OpenAI 兼容）
POST/v1/edits— 旧版编辑别名
POST/v1beta/models/{'{model}'}:generateContent— Gemini 官方格式生图
Midjourney 接口
POST/mj/submit/imagine
POST/mj/submit/blend
POST/mj/submit/describe
POST/mj/submit/edits
POST/mj/submit/video
GET/mj/task/{id}/fetch— 任务查询
GET/mj/image/{id}— 图片代理
提示： /v1/images/variations、/v1/files* 和 fine-tunes* 等路径当前已占位但返回未实现错误，不能直接用于生产。
视频系列
支持 Grok、Sora、Veo、Seedance-2 及国产视频模型（Vidu、Kling、Hunyuan、Mingmou 等）。异步任务提交后通过任务查询获取结果。
POST/v1/videos— 提交视频生成任务（Grok 系列）
GET/v1/videos/{task_id}— 轮询任务状态并获取结果
支持的模型系列
Grok
grok-video-3、grok-video-3-pro、grok-video-3-max
Sora
sora-2
Veo
veo_3_1、veo_3_1-fast
Seedance-2
seedance-2.0-lite、seedance-2.0-pro、seedance-2.0-fast
国产视频模型
Vidu、Kling、Hunyuan、Mingmou、OS、GV、Hailuo、SV、JV
上传管理
图片、视频和媒体资源的预签名上传能力。先上传素材获取公网 URL，再传入生图、图编和视频接口。
POST/api/upload/presign— 获取预签名上传地址
任务管理
异步任务提交后返回任务标识，生成结果需要通过任务查询页面读取。支持 Midjourney、视频生成等异步场景。
任务查询通用模式
GET/mj/task/{id}/fetch— Midjourney 任务查询
GET/v1/videos/{task_id}— 视频任务查询
账户管理
API Key 用量与余额查询，兼容 OpenAI 仪表板格式。
GET/api/usage/token/
API Key 用量与余额
请求示例
curl https://td.geeknow.top/api/usage/token/ \
-H "Authorization: Bearer YOUR_API_KEY"成功响应
{
"code": true,
"message": "ok",
"data": {
"object": "token_usage",
"name": "default-token",
"total_granted": 1000000,
"total_used": 250000,
"total_available": 750000,
"unlimited_quota": false,
"model_limits": {
"gpt-4o": 10000
},
"model_limits_enabled": true,
"expires_at": 1767225600
}
}GET/dashboard/billing/subscription
OpenAI 兼容订阅/余额查询（等价路径 /v1/dashboard/billing/subscription）
响应示例
{
"object": "billing_subscription",
"has_payment_method": true,
"soft_limit_usd": 100.0,
"hard_limit_usd": 100.0,
"system_hard_limit_usd": 100.0,
"access_until": 1767225600
}soft_limit_usd、hard_limit_usd 和 total_usage 最终显示单位受站点配额展示配置影响，不一定始终是美元。
GET/dashboard/billing/usage
OpenAI 兼容用量查询（等价路径 /v1/dashboard/billing/usage）
响应示例
{
"object": "list",
"total_usage": 2500
}常见错误
/api/usage/token/ 缺少 Authorization：
{
"success": false,
"message": "No Authorization header"
}/api/usage/token/ Bearer 格式错误：
{
"success": false,
"message": "Invalid Bearer token"
}OpenAI 兼容余额接口错误：
{
"error": {
"message": "query quota failed",
"type": "upstream_error",
"param": "",
"code": null
}
}常见错误码
| 状态码 | 错误信息 | 类型 | 说明 |
|---|---|---|---|
| 400 | field model is required | invalid_request_error | 请求参数错误，如模型名不存在、消息结构无效 |
| 401 | Invalid API key provided | invalid_request_error | API Key 缺失、无效或过期 |
| 402 | 用户额度不足 | new_api_error | 余额不足 |
| 413 | 请求体过大 | — | Payload Too Large |
| 429 | 当前请求频率过高 | new_api_error | 请求频率超限 |
| 500 | bad response body | new_api_error | 服务端内部错误 |
| 503 | 上游不可用或系统临时过载 | — | 上游不可用 |
认证错误响应示例
{
"error": {
"message": "Invalid API key provided",
"type": "invalid_request_error",
"param": "",
"code": "invalid_api_key"
}
}调用示例
Chat Completions 非流式
curl https://api.quotaflow.ai/openai/v1/chat/completions \
-H "Authorization: Bearer cr_xxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"messages": [{"role": "user", "content": "Return exactly OK."}],
"reasoning_effort": "high",
"stream": false
}'Chat Completions 流式
curl -N https://api.quotaflow.ai/openai/v1/chat/completions \
-H "Authorization: Bearer cr_xxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"messages": [{"role": "user", "content": "Return exactly OK."}],
"reasoning_effort": "high",
"stream": true
}'Responses API
curl https://api.quotaflow.ai/openai/responses \
-H "Authorization: Bearer cr_xxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"input": "Return exactly OK.",
"reasoning": {"effort": "high"},
"store": false
}'查看可用模型
curl https://api.quotaflow.ai/openai/v1/models \
-H "Authorization: Bearer cr_xxxxxxxxxx"OpenAI SDK 调用（JavaScript）
import OpenAI from "openai"
const client = new OpenAI({
apiKey: "cr_xxxxxxxxxx",
baseURL: "https://api.quotaflow.ai/openai/v1"
})
const completion = await client.chat.completions.create({
model: "gpt-5.5",
messages: [{ role: "user", content: "Return exactly OK." }],
reasoning_effort: "high",
stream: false
})
console.log(completion.choices[0].message.content)提示： 请将示例中的 cr_xxxxxxxxxx 替换为您的实际 API 密钥。模型可填 gpt-5.5 或 gpt-5.4；思考强度支持 low / medium / high / xhigh。