本地 API 文档 · 站内留存

SalpX API 参考

SalpX 完全兼容 OpenAI 接口规范——把 base_url 换成 SalpX,一个 Key 即可调用对话、图像、视频等 50+ 模型。本页整合了全部 AI 模型接口与管理接口,所有内容托管在 SalpX 站内,不跳转第三方。

Base URL https://www.salpx.com/v1 鉴权 Bearer <API Key> 规范 OpenAI 兼容

01快速开始

① 在控制台创建 API Key;② Base URL 填 https://www.salpx.com/v1;③ 发起请求:

curl · 对话
curl https://www.salpx.com/v1/chat/completions \
  -H "Authorization: Bearer $SALPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [{"role": "user", "content": "你好,介绍一下你自己"}]
  }'

兼容 OpenAI SDK:仅需把 base_url 设为 https://www.salpx.com/v1,其余代码不变。

02鉴权

所有请求在 HTTP 头携带 API Key:

HTTP Header
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx
  • 控制台 → 令牌管理创建、查看、禁用 Key。
  • Key 可设置额度上限、过期时间、可用分组。
  • 请妥善保管 Key,勿写入前端或公开仓库。

03接口地址 & 兼容

能力方法 / 路径兼容
对话 / 文本POST /v1/chat/completionsOpenAI Chat
图像生成POST /v1/images/generationsOpenAI Images
视频生成POST /v1/videos异步任务
模型列表GET /v1/modelsOpenAI Models

仅“已配置价格并开启”的模型会出现在 /v1/models 与模型广场;未开启模型调用会被拒(见错误码)。

04AI 模型接口

统一模型调用入口,兼容 OpenAI 格式,覆盖聊天、补全、嵌入、图像、视频、实时语音等能力。共 11 类接口:

01
模型列表
获取可用的模型列表。
GET/v1/models
02
聊天 Chat
对话补全接口,支持多轮、推理、工具调用、流式。
POST/v1/chat/completions
03
补全 Completions
传统文本补全接口。
POST/v1/completions
04
嵌入 Embeddings
文本嵌入向量生成接口。
POST/v1/embeddings
05
重排序 Rerank
文档重排序接口。
POST/v1/rerank
06
审查 Moderations
内容安全审核接口(合规工具之一,不替代部署方自身安全治理与上游内容政策;面向公众服务应建立滥用举报、日志审计与处置机制)。
POST/v1/moderations
07
音频 Audio
语音识别与语音合成接口。
POST/v1/audio/speech/v1/audio/transcriptions
08
实时语音 Realtime
实时音频流接口。
POST/v1/realtime
09
图像 Images
AI 图像生成接口。
POST/v1/images/generations
10
视频 Video
AI 视频生成接口(异步任务)。
POST/v1/videos
11
未实现 Unimplemented
占位接口,暂未实现(如文件 Files)。
GET/v1/files

05对话 / 图像 / 视频 示例

对话

请求体
{
  "model": "claude-opus-4-6-anti-thinking",
  "messages": [{"role":"user","content":"用 Python 写快速排序"}],
  "stream": false
}
gpt-5.6-solgpt-5.5claude-opus-4-8 gemini-3.1-pro-lowdeepseek/deepseek-v4-proqwen/qwen3.7-max glm-5kimi-k2.6grok-4.20-0309-reasoning

图像

curl · 图像
curl https://www.salpx.com/v1/images/generations -H "Authorization: Bearer $KEY" \
  -d '{"model":"nano_banana_pro","prompt":"霓虹城市里游动的果冻水母,电影感","n":1}'
nano_banana_pronano_banana_2image2 image2-4kgemini-3.1-flash-imagegpt-image-2

视频(固定时长,按次)

curl · 视频
curl https://www.salpx.com/v1/videos -H "Authorization: Bearer $KEY" \
  -d '{"model":"seedance-2-15s","prompt":"海底果冻水母群缓缓上升,柔光"}'
veo_3_1-fastsora-2-openai-12sseedance-2-10s seedance-2-15sgrok-imagine-1.0-video-superomni_flash
Seedance 2.0 视频生成(含虚拟人/真人形象素材)→ 独立文档
视频按“固定时长 / 按次”收费(seedance-2-10s=一条 10 秒,-15s=一条 15 秒)。请用带时长后缀的具体模型名;通用名 seedance-2/seedance-2-fast 不对外开放。seedance 2.0 / 全能视频S / z-image 系列通过对话接口调用,见 第 06 节 · 视频 / 图像

06视频 / 图像

SalpX 提供 seedance 2.0全能视频S 视频系列与 z-image turbo全能图片 G-2.0 图像系列。经 SalpX 内部适配,统一通过标准对话接口 /v1/chat/completions 调用——提交后 SalpX 同步等待生成完成,把结果(视频 / 图片)URL 放在返回消息里。

调用方式

  • 接口:POST /v1/chat/completionsmodel 填下表模型名。
  • 提示词放在 messages 的 user 文本里;图生 / 多模态把参考图作为 image_url 放进消息内容。
  • 视频时长由模型名锁定(-10s-h / -15s-h),无需传 duration
  • 返回的 assistant 消息内容即结果地址(Markdown ![result](URL) + 纯链接)。

视频 · 文生视频示例

curl · 文生视频
curl https://www.salpx.com/v1/chat/completions -H "Authorization: Bearer $KEY" \
  -d '{
    "model": "seedance2-fast-t2v-10s-h",
    "messages": [{"role":"user","content":"一只柴犬在海边奔跑,电影感,竖屏"}]
  }'

图生视频选 seedance2-i2v-15s-h 等并在消息带 image_url(首帧);多模态 seedance2-mm-10s-h 可带多张图(≤9);全能视频S omni-s-* 默认竖屏 9:16。

视频为异步生成,单条可能数十秒至数分钟,请把客户端 / HTTP 超时设为 ≥ 600 秒。生成失败、超时或未返回结果一律按失败处理并自动退款,不产生扣费。全能视频S 为低价档、偶发不稳定。

视频 · 图生视频(按秒计费)grok-1.5-video-super

同样通过 /v1/chat/completions 调用;图生视频,按秒计费。与固定时长模型不同,必须传顶层 duration(整数秒,6–30),扣费 = 每秒单价 × duration。分辨率由模型名锁定(-480p / -720p),无需传 resolution

价格更新时间:2026-07-05(人民币 / 单位:元/秒);最终以模型广场实时价格为准。

模型名类型分辨率价格
grok-1.5-video-super-480p图生视频 · 按秒480p(锁定)¥0.04/秒
grok-1.5-video-super-720p图生视频 · 按秒720p(锁定)¥0.04/秒
curl · 图生视频(按秒)
curl https://www.salpx.com/v1/chat/completions -H "Authorization: Bearer $KEY" \
  -d '{
    "model": "grok-1.5-video-super-480p",
    "messages": [{"role":"user","content":"门口,走进会议室,浅米外套、黑色墨镜,安静站定"}],
    "duration": 8,
    "aspectRatio": "9:16",
    "imageUrls": ["https://你的参考图.png"]
  }'

必填duration(6–30 秒整数)、提示词(messages)。可选aspectRatio(枚举 2:3 / 3:2 / 1:1 / 16:9 / 9:16,默认 9:16)、imageUrls(参考图,最多 7 张,也可用消息内 image_url)。计费示例:8 秒 × ¥0.04/秒 = ¥0.32

图生视频建议传参考图(imageUrls)。视频为异步生成,请把客户端 / HTTP 超时设为 ≥ 600 秒;生成失败 / 超时 / 未返回结果一律按失败处理并自动退款,不扣费。

图像 · z-image turbo(按次)

同样通过 /v1/chat/completions 调用,返回图片 URL;亚秒级生成、支持中英文文字渲染。

价格更新时间:2026-06-15(人民币 / 单位:元)。

模型名类型说明价格
z-image-turbo-h文生图prompt + aspectRatio(默认 9:16)+ outputFormat(png)¥0.05/次
z-image-turbo-i2i-h图生图需参考图(消息带 image_url 或传 imageUrl)+ prompt¥0.0625/次
curl · 文生图
curl https://www.salpx.com/v1/chat/completions -H "Authorization: Bearer $KEY" \
  -d '{
    "model": "z-image-turbo-h",
    "messages": [{"role":"user","content":"霓虹城市夜景,赛博朋克,竖屏 9:16"}],
    "aspectRatio": "9:16"
  }'
curl · 图生图(带参考图)
curl https://www.salpx.com/v1/chat/completions -H "Authorization: Bearer $KEY" \
  -d '{
    "model": "z-image-turbo-i2i-h",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "赛博朋克霓虹风格,蓝紫色调"},
        {"type": "image_url", "image_url": {"url": "https://your-cdn.com/source.jpg"}}
      ]
    }],
    "aspectRatio": "1:1"
  }'

响应格式

同步返回 OpenAI 兼容 chat.completion。图片 URL 在 choices[0].message.content,格式为 markdown ![result](URL) 后跟一行纯链接,方便正则提取:

响应示例
{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "z-image-turbo-h",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "![result](https://cdn.salpx.com/files/xxxx.png)\n\nhttps://cdn.salpx.com/files/xxxx.png"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 18, "completion_tokens": 105
  }
}
实测耗时 25–35 秒(含排队与生成),请把客户端 / HTTP 超时设为 ≥ 120 秒;连接层失败、生成失败或返回无 URL 一律按失败处理并 自动退款,不产生扣费。图片托管在云存储,保留期有限,建议第三方收到 URL 后自行下载入库。

图像 · 全能图片 G-2.0(按次)

全能图片 G-2.0 文生图 / 图生图。通过 /v1/chat/completions 调用,返回图片 URL。相比 z-image turbo,G-2.0 支持 更丰富的宽高比枚举(含 21:9、9:21、3:1、1:3 等极端比例)和 1k / 2k / 4k 分辨率选项,适合海报 / 广告物料场景。

价格更新时间:2026-06-22(人民币 / 单位:元)。

模型名类型说明价格
image-g-2-h文生图prompt + aspectRatio + resolution(默认 1k)¥0.12/次
image-g-2-i2i-h图生图prompt + 参考图(消息带 image_url 或传 imageUrls 数组)+ aspectRatio + resolution¥0.12/次
image-g-2-official-i2i-h图生图 · 官方稳定版prompt + 参考图 imageUrls + aspectRatio + resolution + quality(两者组合决定扣费档)按档 ¥0.19–4.16/次(见下表)

官方稳定版(image-g-2-official-i2i-h)· 按档动态计费

官方稳定版必须同时传 resolution(1k/2k/4k) 与 quality(low/medium/high),两者组合决定单次价格(按下表实时扣费,非固定价):

quality \ resolution1k2k4k
low¥0.19¥0.38¥0.57
medium¥0.38¥0.76¥1.13
high¥1.39¥2.77¥4.16
📌 调用POST /v1/images/generations,body 传 model / prompt / imageUrls / resolution / quality(可选 aspectRatio)。
⚠️ quality 或 resolution 非法/缺失会返回 400(中英双语),不出图、不扣费。
🖼️ 图源要求imageUrls 必须是上游可稳定拉取的公网图(1–10 张,每张 ≤10MB);GitHub raw、需登录/防盗链的链接可能拉取失败被拒。
curl · 官方稳定版图生图
curl https://www.salpx.com/v1/images/generations -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "image-g-2-official-i2i-h",
    "prompt": "把客厅改造成植物园温室风格,保持空间结构不变",
    "imageUrls": ["https://your-cdn.com/room.jpg"],
    "aspectRatio": "16:9",
    "resolution": "2k",
    "quality": "medium"
  }'

参数枚举

参数必填枚举 / 范围
promptString,长度 1–20000
aspectRatio1:1, 3:2, 2:3, 5:4, 4:5, 16:9, 9:16, 21:9, 3:4, 4:3, 9:21, 1:2, 2:1, 1:3, 3:1
resolution1k / 2k / 4k(默认 1k;2k/4k 因稳定性不保证精准输出,多数情况下仍返回 1k 图)
imageUrlsi2i 必填String 数组,元素为公网 URL 或 data:image/...;base64,... 格式;亦可用消息内 image_url 替代
curl · 文生图
curl https://www.salpx.com/v1/chat/completions -H "Authorization: Bearer $KEY" \
  -d '{
    "model": "image-g-2-h",
    "messages": [{"role":"user","content":"未来感咖啡馆海报,霓虹招牌 CyberBrew,赛博朋克"}],
    "aspectRatio": "16:9",
    "resolution": "1k"
  }'
curl · 图生图(带参考图)
curl https://www.salpx.com/v1/chat/completions -H "Authorization: Bearer $KEY" \
  -d '{
    "model": "image-g-2-i2i-h",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "把苹果改成青绿色,其余构图不变"},
        {"type": "image_url", "image_url": {"url": "https://your-cdn.com/red-apple.png"}}
      ]
    }],
    "aspectRatio": "1:1",
    "resolution": "1k"
  }'

i2i 也支持直接传 imageUrls(顶层数组),等效于消息内 image_url;批量参考多张图时优先用 imageUrls

实测耗时 20–40 秒(含排队);图片 URL 24 小时后失效,请收到后立即下载入库。生成失败 / 超时 / 无 URL 一律按失败处理并 自动退款,不产生扣费。稳定性提示:2k/4k 分辨率属"尽力而为",不保证按需输出。

替代路径 · 标准 OpenAI 图像端点 /v1/images/generations

除上面的 /v1/chat/completions 兼容路径外,全部图像模型(z-image-turbo-h / z-image-turbo-i2i-h / image-g-2-h / image-g-2-i2i-h)也支持标准 OpenAI 图像生成端点。这条路径对接 OpenAI SDK 客户端时无需额外解析 markdown,data[].url 直接拿图。

curl · OpenAI 标准图像端点
curl https://www.salpx.com/v1/images/generations -H "Authorization: Bearer $KEY" \
  -d '{
    "model": "image-g-2-h",
    "prompt": "未来感咖啡馆海报,霓虹招牌 CyberBrew",
    "size": "1024x1024",
    "resolution": "1k"
  }'
响应示例
{
  "created": 1782131476,
  "data": [{ "url": "https://cdn.salpx.com/files/xxxx.png" }]
}
size → aspectRatio 自动映射
OpenAI size映射后 aspectRatio
1024x1024 / 512x512 / 256x256 / 768x7681:1
1024x15362:3
1536x10243:2
1024x17929:16
1792x102416:9
auto / 缺省自适应

也可以直接传 aspectRatio / resolution / imageUrl 顶层字段,优先级高于 size 推导。图生图模型 (*-i2i-h) 仍需 imageUrl / imageUrls仅支持 JSON 请求,文件直传 (multipart) 暂未支持,请先把图片上传到可公开访问的 URL。

07应用 & Skills 接入

SalpX 兼容 OpenAI 接口规范,可直接作为模型后端接入主流 AI 应用与客户端。多数应用只需三步:填 API 地址 https://www.salpx.com/v1、填 API Key、选 模型名

可直接接入的应用(示例)

Cherry StudioOpenClawLangBot AstrBotClineDeepChat Claude CodeCodex CLIOpenAI 兼容客户端

凡支持“自定义 OpenAI 接口”的客户端均可接入:把服务地址改为 SalpX、密钥用 SalpX 的 Key 即可。

Codex 接入(命令行版 CLI,推荐)

OpenAI Codex 接入 SalpX 只需两个文件,都在用户目录 ~/.codex/ 下(Windows:C:\Users\<用户名>\.codex\)。最省事:到「控制台 → 令牌管理」复制对应系统的一键配置命令,已自动填好下面全部内容;手动配置见下。

桌面版 Codex 在部分 Windows 会报“无法设置非管理员沙盒”(应用自身问题,配置改不掉),请改用 CLI 版npm install -g @openai/codex

~/.codex/config.toml

config.toml
model_provider = "salpx"
model = "gpt-5.6-luna"
model_reasoning_effort = "high"
preferred_auth_method = "apikey"
approval_policy = "never"
sandbox_mode = "danger-full-access"

[model_providers.salpx]
name = "SalpX"
base_url = "https://www.salpx.com/v1"
wire_api = "responses"
requires_openai_auth = true

顶层键(model_provider 等)必须放在所有 [ ] 表之前,否则会被并入后面的表而读不到;wire_api 必须为 "responses"(不再支持 chat);sandbox_mode 用于绕过沙盒初始化报错。

~/.codex/auth.json

auth.json
{ "OPENAI_API_KEY": "sk-你的SalpX令牌" }

③ 生效与验证:改完完全退出并重开终端 / Codex(不是最小化),配置才会重新加载。运行 codex 随便问一句能正常回复即成功;也可先用 curl 验证接口连通:

curl · 验证
curl -s https://www.salpx.com/v1/chat/completions \
  -H "Authorization: Bearer 你的Key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-luna","messages":[{"role":"user","content":"回复OK"}],"max_tokens":10}'

可用模型:把 model 改成需要的模型名即可,例 gpt-5.6-sol(最强)等;完整可用模型以 /v1/models 与模型广场为准。常见问题:401 检查 Key 是否正确/未禁用;模型无权限 换一个 /v1/models 里有的模型名;没生效 确认路径正确、已完全重启、model_provider 在文件顶部;Windows 文件须 UTF-8 无 BOM(建议 VS Code,别用记事本),npm 报禁止脚本则 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Claude Code 接入

安装 npm install -g @anthropic-ai/claude-code,设三个环境变量后开新终端运行 claudeANTHROPIC_BASE_URL=https://www.salpx.com不带 /v1,客户端自动补 /v1/messages,带了会变 /v1/v1 报 404)、ANTHROPIC_AUTH_TOKEN=你的令牌ANTHROPIC_MODEL=claude-…。或直接用令牌管理里的一键命令。

Skills(在 AI 编辑器内管理)

SalpX 基于 New API,兼容其 Skills 能力:在 Claude Code、Codex、OpenClaw 等 AI 编码助手里可直接查询可用模型、管理令牌、查看分组与余额,无需切换到后台。

为保证站内留存,本页不外链第三方;上述应用与工具名称仅作兼容性说明,配置时把对应“API 地址 / Base URL”指向 https://www.salpx.com/v1 即可。

08管理接口

用于平台配置、用户体系、渠道、模型、令牌、兑换码、支付与日志管理(多为站点自用后台)。共 17 类接口:

01
系统
系统信息与状态接口。
GET/api/status
02
系统设置
系统配置管理接口。
GET/api/option
03
用户认证
用户登录、注册、密码管理等接口。
POST/api/user/login
04
用户管理
用户信息管理接口。
GET/api/user/self
05
双因素认证
2FA 双因素认证接口。
GET/api/user/2fa/status
06
OAuth
第三方 OAuth 登录接口。
GET/api/oauth/github
07
渠道管理
API 渠道配置管理接口。
GET/api/channel
08
模型管理
模型配置管理接口。
GET/api/models
09
令牌管理
API 令牌管理接口。
GET/api/token
10
兑换码
兑换码管理接口。
GET/api/redemption
11
支付
支付与充值接口。
GET/api/user/topup
12
日志
使用日志查询接口。
GET/api/log
13
统计
数据统计接口。
GET/api/data
14
任务
异步任务管理接口。
GET/api/task
15
分组
用户分组管理接口。
GET/api/group
16
供应商
供应商管理接口。
GET/api/vendors
17
安全验证
安全验证相关接口。
GET/api/verify/status

09模型与计费

  • 按量计费:文本类按 token(输入 + 输出)计费。
  • 按次计费:图像、视频等按每次调用固定价计费(视频按固定时长,如 10s / 15s)。
  • 不同分组对应不同渠道/价格;可用模型与实时价格见模型广场。

10错误码

HTTPcode含义处理
400invalid_request请求参数错误(如图生图缺 image_url、不支持的字段)按返回 message 修正请求
401invalid_api_key / APIKEY_USER_NOT_FOUNDKey 无效、已禁用或上游中转密钥不匹配控制台核对 Key;若调用经自建中转,检查中转 base_url / 鉴权头
403insufficient_quota令牌额度不足或令牌被限额控制台充值或调高令牌额度
404model_not_found / model_price_error模型不存在、当前分组不可用、或未配置价格核对模型名 / 令牌分组;model_price_error 拦截在计费前,不扣费
429rate_limit_exceeded触发并发或速率限流降低并发或指数退避重试
500do_request_failed上游连接层失败(DNS / TLS / 拒连);SalpX 内部已加自动重试失败 自动退款;客户端可换模型或稍后重试
502upstream_error / no_result上游返回错误 / 异步生成完成但无 URL失败 自动退款;可重试或换模型
504gateway_timeout异步任务超过最长等待(视频上限 ~20 分钟)失败 自动退款;高峰期错峰重试
退款保证:所有上游侧失败(5xx 系列)SalpX 一律按失败处理并自动退款,不会出现"扣费但没拿到结果"。model_price_error 拦截在计费前,更不会扣费。

11限流 & 分组

  • 令牌可绑定分组,分组决定可用模型与价格;auto 分组按优先级自动择优。
  • 并发与频率限制可在控制台查看;触发限流返回 rate_limit_exceeded
  • 同一能力建议复用一个 Key,并在服务端做好重试与超时处理。

12SDK 示例 & 批量调用

SalpX 完全兼容 OpenAI SDK——把 base_url 指向 https://www.salpx.com/v1api_key 用 SalpX 令牌,即可调用所有模型(含视频 / z-image 系列)。

Python(openai 官方 SDK)

pip install openai
from openai import OpenAI

client = OpenAI(
    api_key="sk-…",
    base_url="https://www.salpx.com/v1",
)

resp = client.chat.completions.create(
    model="z-image-turbo-h",
    messages=[{"role": "user", "content": "霓虹城市夜景"}],
    extra_body={"aspectRatio": "9:16"},
    timeout=120,
)
print(resp.choices[0].message.content)
# content 形如:![result](https://...png)\n\nhttps://...png

Node.js(openai SDK)

npm i openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-…",
  baseURL: "https://www.salpx.com/v1",
  timeout: 120000,
});

const resp = await client.chat.completions.create({
  model: "z-image-turbo-h",
  messages: [{ role: "user", content: "霓虹城市夜景" }],
  // SalpX 扩展参数通过 SDK 的 body extra 透传:
  aspectRatio: "9:16",
} as any);

console.log(resp.choices[0].message.content);

Go(net/http 原生)

无第三方依赖
package main

import (
  "bytes"; "fmt"; "io"; "net/http"; "time"
)

func main() {
  body := []byte(`{"model":"z-image-turbo-h","messages":[{"role":"user","content":"霓虹城市"}],"aspectRatio":"9:16"}`)
  req, _ := http.NewRequest("POST", "https://www.salpx.com/v1/chat/completions", bytes.NewReader(body))
  req.Header.Set("Authorization", "Bearer sk-…")
  req.Header.Set("Content-Type", "application/json")
  cli := &http.Client{Timeout: 120 * time.Second}
  resp, _ := cli.Do(req)
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}

批量调用模式

图像 25–35s / 视频数十秒至数分钟,串行会显著降低吞吐。推荐并发模式(每个令牌并发上限 5–10,更高请联系 SalpX 调额):

Python · asyncio.gather
import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    api_key="sk-…",
    base_url="https://www.salpx.com/v1",
    timeout=120,
)

async def gen(prompt):
    r = await client.chat.completions.create(
        model="z-image-turbo-h",
        messages=[{"role": "user", "content": prompt}],
        extra_body={"aspectRatio": "9:16"},
    )
    return r.choices[0].message.content

async def main():
    prompts = ["霓虹城市夜景", "深海果冻水母", "赛博朋克街景"]
    results = await asyncio.gather(
        *[gen(p) for p in prompts],
        return_exceptions=True,  # 单条失败不拖整组
    )
    for r in results:
        print(r)

asyncio.run(main())

实现要点

  • 失败处理:上游侧错误(5xx)SalpX 自动退款。客户端只需捕获异常即可,不必为"扣了费没出结果"做补偿逻辑
  • 超时:客户端 timeout ≥ 120s(图像)或 ≥ 600s(视频);SalpX 内部上游轮询最长 20 分钟,超时统一返回 504 并退款。
  • 并发上限:默认每令牌并发 ≤ 10;超出返回 429 rate_limit_exceeded,需指数退避或申请上调。
  • 对账字段:响应 usage 中包含本次任务 ID,可用于回流对账。
  • 结果提取:图片 / 视频 URL 在 choices[0].message.content,第一行 markdown ![result](URL) 后紧跟一行纯链接;推荐用 re.findall(r'https?://\S+', content)[0] 取首个链接。

13命令行工具(CLI)

经验法则:HTTP / SDK / 多数客户端用 https://www.salpx.com/v1;而 Claude Code、Gemini CLI、Codex CLI 用根地址 https://www.salpx.com(不带 /v1)。改完配置需重启终端 / 进程才生效。

Claude Code

环境变量指向根地址(不带 /v1),改完重启终端。

shell
export ANTHROPIC_BASE_URL="https://www.salpx.com"
export ANTHROPIC_AUTH_TOKEN="YOUR_KEY"
export ANTHROPIC_MODEL="claude-opus-4-8"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

macOS 从 Dock 启动的应用不继承 shell 变量——请把上面三条写进 ~/.claude/settings.jsonenv 字段。

Gemini CLI

把 Gemini CLI 指向根地址。

shell
export GOOGLE_GEMINI_BASE_URL="https://www.salpx.com"
export GEMINI_API_KEY="YOUR_KEY"
export GEMINI_MODEL="gemini-3.5-flash"

Codex CLI

~/.codex/config.toml 配置自定义 provider,密钥放 ~/.codex/auth.json

~/.codex/config.toml
model_provider = "salpx"
model = "gpt-5.6-luna"
disable_response_storage = true
network_access = "enabled"

[model_providers.salpx]
name = "SalpX"
base_url = "https://www.salpx.com"
wire_api = "responses"
requires_openai_auth = true
~/.codex/auth.json
{ "OPENAI_API_KEY": "YOUR_KEY" }

Codex 一键安装

一个脚本装好 Codex CLI 并配好 SalpX——ChatGPT Codex 桌面应用与 CLI 都适用。

⚠️ 运行前把脚本里的 testkey 换成你自己的 SalpX Key(控制台获取)。
install-codex.sh
#!/usr/bin/env bash
set -euo pipefail

# ⚠️ 把 testkey 换成你自己的 SalpX Key
SALPX_KEY='testkey'

CODEX_DIR="$HOME/.codex"
mkdir -p "$CODEX_DIR"

if command -v npm >/dev/null 2>&1; then
  npm install -g @openai/codex || echo "Codex CLI 安装失败,请手动:npm install -g @openai/codex"
else
  echo "未找到 npm。CLI 需先装 Node.js LTS(nodejs.org);仅用桌面应用可忽略。"
fi

[ -f "$CODEX_DIR/config.toml" ] && cp "$CODEX_DIR/config.toml" "$CODEX_DIR/config.toml.bak.$(date +%Y%m%d%H%M%S)"
[ -f "$CODEX_DIR/auth.json" ] && cp "$CODEX_DIR/auth.json" "$CODEX_DIR/auth.json.bak.$(date +%Y%m%d%H%M%S)"

cat > "$CODEX_DIR/config.toml" <<'EOF'
model_provider = "salpx"
model = "gpt-5.6-luna"
model_reasoning_effort = "high"
preferred_auth_method = "apikey"

[model_providers.salpx]
name = "SalpX"
base_url = "https://www.salpx.com/v1"
wire_api = "responses"
EOF
chmod 600 "$CODEX_DIR/config.toml"

printf '{\n    "auth_mode": "apikey",\n    "OPENAI_API_KEY": "%s"\n}\n' "$SALPX_KEY" > "$CODEX_DIR/auth.json"
chmod 600 "$CODEX_DIR/auth.json"

echo "SalpX Codex 配置完成($CODEX_DIR)。请完全退出并重启 Codex / 终端。"
[ "$SALPX_KEY" = "testkey" ] && echo "警告:仍是占位 testkey,请编辑 ~/.codex/auth.json 填你自己的 Key。"

存为 install-codex.sh 后运行 bash install-codex.sh,或直接粘进终端执行。

14桌面端与客户端

CC-Switch

Claude Code 端点切换器。按下表把每个供应商分组映射到对应客户端与地址:

映射
OpenAI            → Codex        → https://www.salpx.com
Anthropic/Claude  → Claude Code  → https://www.salpx.com
Gemini            → Gemini CLI   → https://www.salpx.com

OpenCode

opencode.json 加一个自定义 provider。

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "baseURL": "https://www.salpx.com/v1",
        "apiKey": "YOUR_KEY"
      }
    }
  }
}

OpenClaw

~/.openclaw/openclaw.json 定义自定义 provider,密钥放在 env 块里。

~/.openclaw/openclaw.json
{
  "env": { "SALPX_API_KEY": "YOUR_KEY" },
  "agents": {
    "defaults": { "model": { "primary": "salpx/gpt-5.6-luna" } }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "salpx": {
        "baseUrl": "https://www.salpx.com/v1",
        "apiKey": "${SALPX_API_KEY}",
        "api": "openai-responses",
        "models": [{ "id": "gpt-5.6-luna", "name": "GPT-5.6 Luna" }]
      }
    }
  }
}

Hermes

通过 ~/.hermes/config.yaml 配置,或用 hermes model 交互式设置。

~/.hermes/config.yaml
model:
  default: gpt-5.6-luna
  provider: custom
  base_url: https://www.salpx.com/v1
  api_key: YOUR_KEY

Cherry Studio

桌面 LLM 客户端,添加一个自定义 OpenAI 供应商:

  • 设置 → 模型服务 → 添加自定义供应商
  • API Key:YOUR_KEY
  • API 地址:https://www.salpx.com/v1(只填到 /v1,其余自动补全)
  • 手动添加模型 ID(如 gpt-5.6-luna),再点"检查连接"

WorkBuddy

~/.codebuddy/models.json 加模型,用完整端点路径,并以 UTF-8(无 BOM)保存。

~/.codebuddy/models.json
{
  "models": [
    {
      "id": "gpt-5.6-luna",
      "name": "GPT-5.6 Luna (SalpX)",
      "vendor": "OpenAI",
      "url": "https://www.salpx.com/v1/chat/completions",
      "apiKey": "YOUR_KEY",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    }
  ],
  "availableModels": ["gpt-5.6-luna"]
}

DeskClaw

DeskClaw 是 OpenClaw 的桌面封装,自带内置模型、界面里没有明确的"自定义端点"入口。若你的版本读取标准 OpenClaw 配置,用上面 OpenClaw 的方法(~/.openclaw/openclaw.json)即可。

非官方文档项,请按你的 DeskClaw 版本确认是否读取 ~/.openclaw/openclaw.json

Trae

字节跳动的 AI IDE。注意:Trae 目前不支持自定义 base_url(只能选内置供应商列表),因此无法像其它客户端那样直接填 SalpX 地址。可选两种接法:

  • 本地代理(当前可用):用开源工具 Trae-Proxy(GitHub 搜 arch3rPro/Trae-Proxy)把 Trae 发往 OpenAI 的请求拦截、转发到 SalpX。步骤:① 启动 Trae-Proxy,后端设为 https://www.salpx.com/v1、密钥填你的 SalpX Key;② 安装它提供的自签证书;③ 按其说明改本机 hosts,把 OpenAI 域名指向本地代理;④ 回到 Trae → 添加模型 → 供应商选 OpenAI → 自定义 model ID(如 gpt-5.6-luna)。
  • 官方原生(视版本):若你的 Trae 版本已开放"自定义端点 / base_url",直接填 API 地址 https://www.salpx.com/v1 + SalpX Key + 模型名即可。
这是 Trae 侧的产品限制、非 SalpX 限制——SalpX 完全 OpenAI 兼容,Trae 一旦支持自定义端点即可零改动接入。
⚠️ 流式中途断连排查:走 Trae-Proxy 时若报 Stream error: Transport error: request or response body error (origin:downstream),多半不是模型或 SalpX 故障(token 仍在正常生成),而是本地代理这一层的问题。按序排查:① Trae-Proxy 是否缓冲了 SSE——本地代理若不实时透传流,长回答 / 带思考的模型会被判空闲超时而断开,这是头号嫌疑;② 把 Trae-Proxy 及 Trae 的请求 / 流超时调大:空闲(读)超时 ≥ 120 秒、整体请求 ≥ 600 秒(只有一个超时项就设 300–600 秒);③ 若链路上另有反向代理(nginx 等),加 proxy_buffering off 让流实时透传。SalpX 网关侧已内置 SSE 空闲心跳保活(可由管理员开启),能扛住一部分空闲超时。

15进阶 · 开启 Codex 插件(Codex++)

  1. 安装官方 Codex 应用,再从其 releases 安装 Codex++。
  2. 在控制台创建 / 复制一个 API Key。
  3. 打开 Codex++ 工具 → Relay 配置。
  4. 添加配置:Base URL https://www.salpx.com/v1、API Key、模型 gpt-5.6-luna
  5. 保存,通过 Codex++ 启动 Codex,确认 Provider = CodexPlusPlus

16帮助

常见问题

现象解决
401 / invalid_api_key从控制台复制完整 Key,别带多余空格或换行。
403余额不足、Key 被禁用,或该模型不在你的分组内。
404地址 / 路径错了。HTTP/SDK 用 /v1;Claude Code & Gemini CLI 用根地址。
CC-Switch 导入无反应确认 CC-Switch 已安装且 ccswitch:// 协议已注册。
CLI 改了不生效重启进程;环境变量只对新启动的会话生效。

获取权限

控制台 → 令牌管理 创建 API Key,充值后即可调用全部模型。一个 Key 通用所有接口与客户端。