星海API 接口文档

01快速开始

把 base_url 指向本站、填入你的 Key，即可用任意 OpenAI 兼容客户端或 SDK 调用。

curl https://starseaapi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 1024
  }'

02端点与协议

同一枚 Key、同一份模型清单，网关对外提供 四种协议形态。客户端支持哪种就填哪种，计费与鉴权完全一致。

Anthropic Messages 示例

把 Anthropic SDK 的 base_url 指向 https://starseaapi.com（SDK 自行拼接 /v1/messages），模型名填站内在售模型。

curl https://starseaapi.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "glm-5.3",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "你好"}]
  }'

OpenAI Responses 示例

Codex CLI 自 0.147 起只接受 wire_api = "responses"；配置文件 ~/.codex/config.toml 中把 Base URL 填 https://starseaapi.com/v1 并选一款下方支持的模型即可。

curl https://starseaapi.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{
    "model": "glm-5.3-flash",
    "input": "你好"
  }'

已开放 Responses 的 19 款：deepseek-v4-flash、deepseek-v4-flash-0731、deepseek-v4-pro、deepseek-v4-pro-0813、doubao-seed-2.0-lite、doubao-seed-2.0-mini、doubao-seed-2.1-lite、doubao-seed-2.1-pro、doubao-seed-2.1-turbo、doubao-seed-code、doubao-seed-evolving、glm-5.2、glm-5.3、glm-5.3-flash、k3、kimi-k2.6、kimi-k2.7-code、kimi-k2.8-preview、minimax-m3。
暂未开放（调用会提示不支持该端点，换用上面任一模型即可）：deepseek-v4.1-flash、glm-5、glm-5.1、hy3、longcat-2.0、mimo-v2.5、mimo-v2.6-flash、qwen3.6-flash、qwen3.6-plus、qwen3.7-max、qwen3.7-plus、qwen3.8-flash、qwen3.8-max。
注意 /v1/responses/compact（上下文压缩）暂未开放，Codex 触发该请求会失败，建议在配置中关闭自动压缩。

Gemini generateContent 示例

curl https://starseaapi.com/v1beta/models/glm-5.3:generateContent \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: sk-你的密钥" \
  -d '{"contents": [{"parts": [{"text": "你好"}]}]}'

03模型列表

GET /v1/models 返回你的分组当前可用的全部模型（当前 32 个）。家族速览：

在售模型规格表（32 款）

上下文 / 最大输出为各模型官方规格；「能力」不含全模型共有的「文本对话」，均为 推理、代码、视觉理解 的子集。全部 32 款均支持工具调用（Function Calling）与思考链。
「视觉理解」指该模型原生多模态（图片直送上游）；未标注的纯文本模型同样可以收图 —— 由网关先做结构化描述再转交，对调用方完全透明（见「识图」章）。

04对话接口

POST /v1/chat/completions —— 标准 OpenAI 对话端点，支持多模态输入、流式输出与函数调用。

响应结构

{
  "id": "chatcmpl-202609270719051757216358268d9d6",
  "object": "chat.completion",
  "model": "deepseek-v4.1-flash",
  "choices": [{"message": {"role": "assistant", "content": "OK"}, "finish_reason": "stop"}],
  "usage": {
    "prompt_tokens": 85, "completion_tokens": 33, "total_tokens": 118,
    "prompt_tokens_details": {"cached_tokens": 0},        // 上下文缓存命中量
    "completion_tokens_details": {"reasoning_tokens": 31} // 思考链消耗
  }
}

思考型模型在 message 内额外返回 reasoning_content（思维链），计费按 token 正常计算。函数调用时返回 tool_calls 数组。

函数调用示例

{
  "model": "deepseek-v4.1-flash",
  "messages": [{"role": "user", "content": "杭州天气如何？"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "查询指定城市天气",
      "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
    }
  }],
  "tool_choice": "auto"
}

05识图（多模态输入）

• 原生多模态模型（glm-5.3-flash、minimax-m3、doubao-seed-2.1-*、k3、qwen3.6-plus 及 3.8 系列、mimo-v2.5 / mimo-v2.6-flash、deepseek-v4.1-flash 等）：图片直送上游，体验与官方一致。
• 纯文本模型（deepseek-v4-flash、glm-5.3、kimi-k2.7-code、hy3 等）：网关先为图片生成一份结构化描述（主色、文字逐字转录、表格/图表内容、界面元素），再交给模型，对调用方完全透明。
• 适用场景：图片内容理解、OCR 文字提取、表格与图表读取、代码/JSON 截图识别、UI 界面分析。
• 同一张图片全站只解析一次并复用，重复使用响应更快且不产生额外计费。

"messages": [{"role": "user", "content": [
  {"type": "text",      "text": "描述这张图片"},
  {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
]}]

支持 data URI（base64 内联）与公网图片 URL。若某模型识图报错，把模型名反馈客服即可，会在 24 小时内补齐。

06流式输出

"stream": true 时以 SSE 逐块推送：

data: {"choices":[{"delta":{"content":"你"}}]}
data: {"choices":[{"delta":{"content":"好"}}]}
data: [DONE]

流式连接上限 600 秒（该上限约束的是响应头返回前的等待，长输出建议客户端自行放宽读超时）。

07图像生成

图像生成模型沿用与对话一致的两种调用方式（恢复上线后即可用）：

方式一 · 标准图像端点（返回 base64）

curl https://starseaapi.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{
    "model": "qwen-image-3.0-pro",
    "prompt": "白色背景上一个红色圆形，扁平插画风格",
    "n": 1,
    "size": "1024x1024"
  }'

{
  "created": 1789347047,
  "data": [{ "revised_prompt": "白色背景上一个红色圆形，扁平插画风格", "b64_json": "iVBORw0KGgo..." }]
}

方式二 · 对话端点（返回图片链接）

图像模型亦可用 POST /v1/chat/completions 调用 —— 把描述当作普通消息发送，响应正文即 Markdown 图片链接：

// request
{ "model": "qwen-image-3.0-pro",
  "messages": [{"role": "user", "content": "白色背景上一个红色圆形，扁平插画风格，1024x1024"}] }

// response -> message.content
![generated image](https://starseaapi.com/img/xxxxxxxx.png)

08计费与缓存

• 按用量计费：输入、输出分别按模型倍率实时结算，单价为人民币 / 每百万 tokens，各模型价格见服务台「模型价格」页（与官网同价）。
• 缓存计价：输入 = 未缓存输入 + 缓存命中（读取）+ 缓存写入；缓存命中部分按缓存价计费，最低可至输入价的 2%（DeepSeek 系为输入价的 1/50），响应中 cached_tokens 可查命中量。输出无缓存。
• 峰谷时段（DeepSeek 系）：工作日 9:00–12:00、14:00–18:00 为高峰，按低谷价的 2 倍 计费；其余时段与周末全天按低谷价。
• 长上下文分段：部分模型超长输入按更高档位计费 —— 豆包 Seed 2.0 分 32K / 128K 两档，GLM-5 系分 32K 档，通义 3.6 / 3.7 分 256K 档，MiniMax-M3 分 512K 档；具体档位单价见「模型价格」页悬停提示。
• 失败自动重试：同模型自动多路重试（最多 6 次），对调用方透明。
• 消费明细在控制台「日志」页逐条可查；页面时间均为北京时间（UTC+8）。

如何提高缓存命中（省钱 · 提速）

1. 固定内容放最前面：系统提示词、工具定义、长文档、固定示例放请求最前面；会变的内容（本次问题、时间戳、随机 ID）放最后。
2. 同一段前缀复用同一请求头：客户端支持时，给同一会话固定传同一个 X-Session-Id（或 prompt_cache_key），让同前缀请求固定送到同一条上游线路。
3. 不要把时间戳、当天日期、随机 ID 写进 system prompt —— 这会让每次请求的前缀都不同，缓存永不命中。

09错误码

错误响应统一为 {"error":{"code":"...","message":"...","type":"new_api_error"}}，message 末尾附带 request id，报障时请一并提供。

{
  "error": {
    "code": "invalid_token",
    "message": "API Key 无效：该 Key 不存在。请到 starseaapi.com 控制台「令牌」页复制正确的 API Key（兑换码不能作为 API Key 使用） (request id: 202609270719054285023828268d9d6XsjFVr5u)",
    "type": "new_api_error"
  }
}

10限制

• 请求体上限 128 MB；流式连接上限 600 秒。
• 单次输出上限随模型而异（实测档位 32K / 64K / 128K / 131K / 256K / 384K 不等，见规格表）；建议客户端不显式传 max_tokens，由网关按模型上限处理，可从根本上避免超限 400。
• 上下文窗口上限随模型而异（200K – 1.05M），超长输入可能触发更高计费档位（见「计费与缓存」章）。
• 新注册账户默认限额，可在控制台申请调整。
• 禁止违法违规用途（详见用户协议）；禁止转售 / 共享账号，违者可能被禁用。

11常见问题

12工具一键导入

访问 Key 服务台：粘贴 Key 本地查余额（不上传明文）、兑换码秒充值、查看模型价格，并一键生成配置到 WorkBuddy / ZCode / TRAE CLI / Claude Code / Codex / Qwen Code / OpenCode / Kilo Code / Pi / OpenClaw / CodeBuddy / MiMo Code / Gemini CLI / Factory Droid 等 133 款客户端与框架（含 Windows SmartScreen / Mac Gatekeeper 拦截处理说明，以及 base_url、模型清单、协议类型的自动写入）。