OpenAI 兼容格式
适用于 Codex、Cherry Studio、Chatbox、OpenAI SDK 等。
https://huoxingapi.com/v1从创建密钥到完成第一次请求,再到 Claude Code、Codex 与桌面客户端配置,这份文档会带你走完整个接入过程。
API Key、Base URL 和模型名称。不要把网页地址直接当成接口地址。
已按“新手操作、软件配置、模型接口、账户与排查”重新整理。左侧目录可逐级展开;特殊模型接口请先核对模型详情中的协议与端点。
价格、充值、分组、API Key、URL、日志、错误码与常见误区。
Claude Code、Codex、CC-Switch、Cursor、VS Code、Gemini CLI、OpenCode 等。
Cherry Studio、Chatbox、WorkBuddy、NextChat、LobeChat 与酒馆。
Dify、n8n、Coze、FastGPT、OpenClaw、Hermes、OpenWebUI 等。
OpenAI、Anthropic、Gemini、国产模型、图片、视频、音频与 3D。
账户信息、密钥管理、调用日志、统计、导出与费用核对。
具体能力是否可用仍以火星 API 模型广场和模型详情为准;不会把其他平台的专用端点直接写成火星 API 已支持。
下面以 OpenAI 兼容格式为例。复制前,请先把示例密钥和模型名称换成你控制台中的真实值。
登录火星 API 后,在左侧进入“API 密钥”。
建议为不同项目分别创建密钥,后续更容易统计、限额和停用。
在模型广场复制准确的模型 ID,然后用下面的请求测试。
curl https://huoxingapi.com/v1/chat/completions \ -H "Authorization: Bearer sk-hx-你的密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "请填写模型ID", "messages": [{"role":"user","content":"你好,火星API"}] }'
密钥应保存在服务端环境变量中,不要写入前端页面、公开仓库或截图。
不同客户端对 Base URL 的拼接方式不同。若软件会自动补全 /v1,请按软件提示填写。
适用于 Codex、Cherry Studio、Chatbox、OpenAI SDK 等。
https://huoxingapi.com/v1适用于 Claude Code 和直接调用 /v1/messages。
https://huoxingapi.com模型最终费用由模型价格、实际 Token 用量和所选分组倍率共同决定。实时价格以“模型广场”和单条使用日志为准。
确认输入、输出、缓存读取与缓存写入价格。
创建密钥时按稳定性、适配能力与预算选择。
请求完成后可查看 Token 明细、倍率和最终费用。
最终费用 = 输入费用 + 输出费用 + 缓存费用,再乘以该密钥所属分组的倍率。动态计费模型以日志中实际命中的价格阶梯为准。
| 选择维度 | 你需要关注 | 建议 |
|---|---|---|
| 价格 | 输入 / 输出 / 缓存单价与分组倍率 | 先小额测试,再投入正式任务 |
| 稳定性 | 延迟、成功率、上游适配 | 重要生产任务优先稳定分组 |
| 上下文 | 单次请求的输入 Token 数 | 超长上下文先确认模型限制 |
在控制台左侧点击“钱包”,或从账户概览点击“余额充值”。
按页面可用的支付方式完成充值;支付结果以钱包到账记录为准。
充值记录与模型消费记录分开显示,便于对账。
密钥是请求鉴权凭证。建议按“项目 / 客户端 / 环境”拆分创建,避免多人共用同一枚密钥。
方便统计消耗、设置额度和单独停用,不会影响其他项目。
新密钥生成后立即妥善保存;若泄露,请停用并重新创建。
Claude Code 使用 Anthropic 原生格式。Base URL 不带结尾 /v1。
ANTHROPIC_BASE_URL=https://huoxingapi.com ANTHROPIC_AUTH_TOKEN=sk-hx-你的密钥
安装完成后运行 claude doctor 检查当前版本和运行环境;Windows 用户优先使用 WSL 或 Git Bash。
Base URL 使用站点根地址,不要追加 /v1;密钥放入 ANTHROPIC_AUTH_TOKEN。
进入一个测试项目运行 claude,发送一句短消息;成功后再用于正式代码仓库。
https://huoxingapi.comANTHROPIC_AUTH_TOKENAnthropic /v1/messages请从火星 API 模型广场复制当前可用的准确模型 ID,不要根据展示名称自行猜测。
使用 OpenAI 兼容地址,将模型名替换为模型广场中实际可用的 GPT / Codex 模型 ID。
model_provider = "huoxing" model = "请填写模型ID" [model_providers.huoxing] name = "Huoxing API" base_url = "https://huoxingapi.com/v1" env_key = "OPENAI_API_KEY"
在火星 API 控制台单独创建一枚密钥,便于设置额度、统计消耗和随时停用。
把密钥保存为 OPENAI_API_KEY,然后在 Codex 配置中添加火星 API 提供商。
不要照搬示例模型名。先用短任务测试读取文件和输出,再用于耗时较长的工程任务。
若当前 Codex 版本字段不同,以客户端自己的配置说明为准;Base URL 与密钥仍使用上面的火星 API 参数。
下面这些工具都可以通过自定义 OpenAI 或 Anthropic 服务接入。客户端版本更新后字段名称可能变化,但核心参数一致。
分别为 Claude Code 与 Codex 创建火星 API 提供商配置,切换时选择对应协议。
https://huoxingapi.comhttps://huoxingapi.com/v1在自定义模型或 OpenAI Base URL 中填写兼容地址,再从模型广场复制模型 ID。
https://huoxingapi.com/v1提供商选择 OpenAI Compatible;若使用 Claude 原生工具调用,则改选 Anthropic Compatible。
安装支持自定义提供商的 AI 插件后,按插件协议填写火星 API;Claude Code 插件使用 Anthropic 根地址。
提供商选择 OpenAI Compatible 或 Anthropic Compatible,分别使用对应 Base URL。
推荐通过支持 Gemini 自定义供应商的 CC-Switch 版本配置。原生 Gemini 协议是否可用以模型详情为准。
仅在当前插件版本提供“自定义 OpenAI / Anthropic 端点”时配置;没有该入口时不要强行替换官方登录。
桌面端在提供商设置中新增自定义服务;CLI 可通过配置文件或 CC-Switch 管理供应商。
https://huoxingapi.com/v1若版本支持自定义 OpenAI 兼容供应商,可复用相同参数;先用短任务验证模型和工具调用。
与 CLI 共用 Anthropic 配置思路;客户端若读取系统环境变量,修改后需完全退出并重新打开。
使用 OpenAI 兼容提供商和独立密钥。界面字段随版本变化时,以“Base URL / API Key / Model”三项为准。
若能获取模型列表却无法对话,优先核对模型 ID、请求协议、流式输出和客户端超时。
类型选择 Claude / Anthropic,Base URL 填 https://huoxingapi.com,再填写密钥和 Claude 系列模型 ID。
类型选择 OpenAI Compatible,Base URL 填 https://huoxingapi.com/v1,密钥建议与 Claude 分开创建。
先测试连接,再将当前提供商切换到火星 API。切换后重新打开对应终端,避免读取旧环境变量。
进入 Settings 中的 Models、Providers 或 API Keys;不同版本的菜单名称可能略有变化。
填入火星 API Key、Base URL 和模型广场中的完整模型 ID;若软件自动补全 /v1,则按字段提示去掉重复部分。
普通对话成功后,再测试代码补全、工具调用或 Agent 模式。部分功能可能要求特定模型能力。
多数模型选择 OpenAI Compatible;需要 Claude 原生工具调用时选择 Anthropic Compatible。
填写 Base URL、API Key、模型 ID,并根据任务规模设置最大输出和上下文限制。
首次使用先关闭自动批准或限制工具权限,并为这枚密钥设置额度,避免循环操作持续扣费。
在扩展设置中查找 Provider、API Configuration 或 OpenAI Compatible。只支持官方登录的插件不能直接填中转地址。
OpenAI 兼容用 https://huoxingapi.com/v1;Claude Code / Anthropic 兼容用 https://huoxingapi.com。
Agent 插件首次测试时关闭自动执行命令,为专用 Key 设置额度,确认工具调用正常后再逐步放开权限。
安装方式和 Node.js 版本以 Gemini CLI 当前官方说明为准,不在文档中固定过期的安装命令。
新增自定义供应商,填写火星 API Key、模型 ID 和当前模型详情标注的 Gemini 兼容地址。
若模型只标注 OpenAI 兼容,不要假定 Gemini 原生 CLI 一定可用;可改用支持 OpenAI Compatible 的编程助手。
只有模型详情明确标注 Gemini 原生协议时,才能直接套用 Gemini CLI 自定义供应商配置。
优先选择 OpenAI Compatible;若目标是 Claude 原生工具调用,再选择 Anthropic Compatible。
Base URL、API Key、完整模型 ID 缺一不可。不要复制其他平台的域名、示例密钥或模型别名。
先测试普通对话,再测试读取文件、工具调用和长任务;任一步失败都保留请求 ID 后再调整。
多数桌面客户端都可选择“OpenAI 兼容”或“自定义 OpenAI”,再填写同一套参数。
OpenAI Compatiblehttps://huoxingapi.com/v1从模型广场复制完整 ID在模型服务设置中选择新增服务商,协议选择 OpenAI 或 OpenAI Compatible。
填写火星 API Key、Base URL 和模型 ID,启用该服务商后保存。
先执行连接检查或获取模型,再新建一个短对话。若提示模型不存在,请重新复制完整 ID。
新增自定义提供方,兼容类型选择 OpenAI API。
Base URL 填 https://huoxingapi.com/v1,再填入专用密钥。
如果没有自动列出模型,就把模型广场中的模型 ID 手动添加到可选列表。
本地桌面版可在设置中填写;自己部署的版本通常需要在服务端环境变量或供应商配置中填写。
公开部署时必须由服务端读取密钥,避免浏览器源码或网络请求泄露主账户凭证。
环境变量变更一般要重启对应容器或服务;正式操作前先查看当前版本说明。
在模型服务或供应商设置中确认当前版本是否提供 OpenAI Compatible。没有自定义端点入口时无法直接接入。
使用 https://huoxingapi.com/v1、专用 API Key 和模型广场中的完整模型 ID。
先测试一句短消息,再启用知识库、附件或工具调用;不同能力需要模型本身支持。
不要选择官方账号登录,改用自定义 API / OpenAI Compatible 配置。
模型 ID 必须与模型广场一致;上下文上限不要盲目设得过大,以免单次请求费用异常。
旧会话可能携带很长历史记录。首次测试请新建空白会话,确认正常后再导入角色卡和知识库。
只要工具支持自定义 OpenAI 服务,通常都可以接入。生产工作流建议设置请求超时、重试上限和单任务费用保护。
在模型供应商中使用 OpenAI-API-compatible 类型,填写火星 API Base URL、密钥与模型 ID。
https://huoxingapi.com/v1优先使用允许自定义 Base URL 的 OpenAI 节点;没有该字段时改用 HTTP Request。
/v1/chat/completions根据当前版本选择自定义模型或 HTTP 节点,并确认密钥不会暴露到客户端。
配置 OpenAI 兼容模型供应商;知识库应用还需区分聊天模型与嵌入模型 ID。
对 429、502、503、504 使用有限次数的指数退避;不要对鉴权或余额错误无限重试。
为自动化任务单独创建密钥和额度,避免异常循环调用消耗主账户余额。
在工作区设置中找到模型供应商,选择 OpenAI-API-compatible 或当前版本提供的自定义 OpenAI 插件。
填写 Base URL、API Key 和模型 ID;模型类型按实际能力选择聊天、推理或嵌入。
先建立只有“开始—模型—结束”的最小工作流,成功后再加入知识库、工具和循环节点。
按 Claude、Codex 或 Gemini 用途分别创建,设置分组、额度和有效期,不要导入主账户长期密钥。
Claude 选 Anthropic 根地址;Codex 选 OpenAI Compatible 并填写带 /v1 的地址。
确认连接、模型 ID 和短对话成功,再切换供应商并重新打开终端。
如果当前版本允许自定义 Base URL,可直接创建凭证并填写火星 API 参数。
向 /v1/chat/completions 发送 POST,请求头包含 Bearer 密钥和 JSON 内容类型。
只对 429、502、503、504 做有限重试;401、402、404 应直接停止并记录错误。
能添加 OpenAI 兼容供应商时直接添加;若平台版本不提供该入口,则使用 HTTP 请求节点。
把用户问题写入 messages,再从响应中的助手文本字段读取结果。
单独创建令牌、设置额度并限制循环次数;批量工作流先用少量数据验证。
OPENAI_API_KEY=sk-hx-你的密钥 OPENAI_BASE_URL=https://huoxingapi.com/v1 MODEL_NAME=请填写模型ID
不要复用管理员或个人测试密钥;设置合理额度,并在备注中标明项目和环境。
把密钥保存到平台 Secret、容器环境变量或安全配置中心,不提交到 Git 仓库。
先验证模型列表或发送短请求,再开放给用户;保留请求 ID、状态码和响应时间用于排查。
选择自定义 OpenAI 兼容供应商,填写 https://huoxingapi.com/v1、专用 Key 和模型 ID。
不要照搬其他模型的超长上下文设置;先以模型详情和小额测试为准。
对话正常后再接入 QQ、Telegram 等外部机器人,避免同时排查模型和消息通道。
OpenAI Compatiblehttps://huoxingapi.com/v1从模型广场复制 ID若当前版本仅支持官方账号登录或固定供应商,则不能直接接入;不要修改程序源码绕过鉴权。
有的项目使用 OPENAI_API_BASE、OPENAI_BASE_URL 或供应商专用字段。先查看该项目的示例配置,避免填错后反复重启。
适用于 OpenAI SDK 及支持自定义 Base URL 的客户端。请求路径通常为 /v1/chat/completions。
import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.HUOXING_API_KEY, baseURL: "https://huoxingapi.com/v1", }); const result = await client.chat.completions.create({ model: "请填写模型ID", messages: [{ role: "user", content: "你好" }], });
import os from openai import OpenAI client = OpenAI( api_key=os.environ["HUOXING_API_KEY"], base_url="https://huoxingapi.com/v1", ) response = client.chat.completions.create( model="请填写模型ID", messages=[{"role": "user", "content": "你好"}], )
| 字段 | 是否必填 | 说明 |
|---|---|---|
| model | 是 | 从火星 API 模型广场复制完整模型 ID |
| messages | 是 | 至少包含一条用户消息;长历史会增加输入 Token |
| stream | 否 | 设为 true 时客户端必须正确读取 SSE 流并处理断开 |
| max_tokens | 否 | 限制最大输出;具体字段兼容性以模型详情为准 |
下面用于帮助客户选接口,不代表每个模型都支持全部能力。先在模型广场确认模型能力和端点,再按对应格式调用。
确认鉴权、模型和返回格式正常后再启用流式输出,更容易区分接口问题与客户端流解析问题。
请求使用 x-api-key 与 anthropic-version 请求头,路径为 /v1/messages。
curl https://huoxingapi.com/v1/messages \ -H "x-api-key: sk-hx-你的密钥" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "请填写模型ID", "max_tokens": 1024, "messages": [{"role":"user","content":"你好"}] }'
https://huoxingapi.com/v1/messagesx-api-key: 你的密钥anthropic-version: 2023-06-01优先使用 OpenAI 兼容格式接入 Gemini,这样能复用现有 SDK 和客户端。模型名称请从模型广场复制。
适合聊天、编程和多数第三方客户端。
https://huoxingapi.com/v1仅在模型详情明确标注支持时使用;请求路径、版本与多模态字段以该模型说明为准。
同一系列可能包含不同日期、上下文和多模态版本,必须复制模型广场中的完整 ID。
DeepSeek、通义千问、智谱 GLM 与豆包等模型可在同一 OpenAI 兼容地址下调用,实际可用型号以模型广场为准。
curl https://huoxingapi.com/v1/chat/completions \ -H "Authorization: Bearer sk-hx-你的密钥" \ -H "Content-Type: application/json" \ -d '{"model":"从模型广场复制ID","messages":[{"role":"user","content":"你好"}]}'
多媒体模型的任务提交、状态查询和结果字段差异较大。火星 API 会在模型详情中标注具体协议;未标注前不要直接套用文本接口。
可能提供 Imagine、Blend、Action、Describe、Edit、Video 等能力;具体端点以模型详情为准。
文生图、参考图与编辑可能使用 OpenAI 图片格式或专用任务协议,不能只替换模型名。
确认尺寸、步数、负面提示词、种子和图片返回格式是否由当前通道支持。
适合文字排版类图片时仍要以模型详情中的参数和协议为准。
确认输出格式、尺寸和风格参数;批量生成前先测试最低规格。
区分文生图、单图编辑和多图参考,使用模型详情给出的准确模型 ID。
注意 multipart、图片 URL、Base64 三种输入方式不能混用。
视频通常为异步任务:提交后保存任务 ID,再查询状态直至成功或失败。
官方异步、渠道异步和兼容格式可能并存;创建、查询、下载必须使用同一套协议。
区分文生视频、图生视频和状态查询;时长、比例、分辨率都会影响费用。
保存任务 ID,使用合理轮询间隔;失败、取消或完成后立即停止查询。
生成、歌词、分离和查询任务可能是不同端点。
关注歌词、风格、时长、是否纯音乐及结果文件的有效期。
先确认输入音频来源、支持格式以及结果文件的版权和保存期限。
批量和单任务查询路径可能不同;不要高频轮询。
常见流程为图片或文字生成任务、轮询状态并下载模型文件。
| 接口类型 | 调用前确认 | 日志中保留 |
|---|---|---|
| 图像 | 模型 ID、尺寸、张数、参考图格式 | 请求 ID 与图片任务 ID |
| 视频 | 分辨率、时长、宽高比、异步查询路径 | 任务 ID 与失败原因 |
| 音频 | 歌词、风格、时长与版权使用范围 | 任务 ID 与结果 URL |
| 3D | 输入格式、输出格式与文件大小 | 任务 ID 与下载有效期 |
在模型详情中确认是同步返回、异步任务还是 OpenAI 兼容接口,并复制准确的请求路径。
异步模型提交成功不等于生成完成。必须保存任务 ID,作为后续查询、计费和客服排查依据。
按合理间隔查询,遇到失败状态立即停止;不要每秒高频轮询或对永久失败任务持续重试。
生成文件 URL 可能有有效期。下载完成后保存到自己的存储,并记录内容授权与使用范围。
图片张数、分辨率、视频时长、音频长度或任务次数都可能影响费用。正式批量生成前先用最低规格测试一笔。
目前推荐从控制台完成账户与令牌操作。控制台内部接口可能随版本变化,不建议第三方程序直接依赖未公开的后台路径。
查看用户名、账户状态、余额与个人资料;不要在公开截图中展示隐私信息。
创建、停用、删除密钥,按项目设置分组与额度;密钥明文只安全保存一次。
按时间、用户、令牌、模型和状态筛选,核对输入输出 Token、缓存与最终费用。
查看充值记录和消费明细。对账时以单条请求 ID 与钱包流水为依据。
当前控制台若提供导出功能,可按时间和密钥导出;没有导出入口时先用筛选结果逐条核对。
先选择异常发生的时间段,再按用户名、令牌或模型过滤,避免在大量日志中手工翻找。
核对请求 ID、上游请求 ID、输入输出 Token、缓存读取与写入、倍率、状态和最终费用。
优先使用上游请求 ID 对账;没有上游 ID 时保留本地请求 ID、时间、渠道和结束原因。
不要只看输入 Token 估算。先确认上游是否真实接收、是否产生缓存费用,再决定退款或修正规则。
在接口正式公开前,文档不会编造获取余额、创建密钥或查询日志的路径。
| 现象 | 常见原因 | 先这样处理 |
|---|---|---|
| 401 / 无效密钥 | 密钥错误、失效或请求头格式不对 | 重新复制密钥,确认包含 Bearer 或正确的 x-api-key |
| 402 / 余额不足 | 余额不足或密钥额度用尽 | 检查钱包余额、密钥限额及分组设置 |
| 404 / 模型不存在 | 模型 ID 拼写错误或当前分组不可用 | 从模型广场重新复制模型 ID |
| 429 / 请求过多 | 触发并发或速率限制 | 降低并发,增加指数退避重试 |
| 502 / 504 | 上游暂时不可用或请求超时 | 保留请求 ID,稍后重试或切换可用模型 |
| client_gone | 客户端提前断开或取消流式请求 | 检查客户端超时、网络与主动取消逻辑 |
保存时间、模型、请求 ID、状态码和错误文本;不要复制完整 API Key。
新建空白会话,只发送一句短消息。若成功,问题通常来自历史上下文、工具调用或客户端超时。
没有上游请求 ID 且立即失败时,优先排查本地校验、路由和请求转换;有上游 ID 时再核对渠道记录。
429、502、503、504 可有限重试;401、402、404 和参数错误应先修正配置。
不要发送完整 API Key。提供时间、模型、请求 ID、错误信息与能否复现即可。
进入控制台的“钱包”,选择充值金额并按页面提示完成支付。到账情况以钱包余额和充值记录为准;未到账时保留支付时间与订单信息联系客服。
以火星 API“模型广场”当前展示为准,涵盖 Claude、GPT、Gemini、DeepSeek、通义千问、智谱 GLM 等系列。模型会更新或调整,不在文档中固定一份容易过期的型号清单。
登录控制台,进入“API 密钥”后创建。火星 API 的一枚 Key 可按其分组调用多个模型,不需要分别获取官方 OpenAI、Claude 或 Gemini Key。
在模型广场复制新的完整模型 ID,并替换请求中的 model。如果新模型属于不同分组或协议,还要确认当前 Key 的分组和客户端协议是否兼容。
OpenAI 兼容客户端通常填写 https://huoxingapi.com/v1;Claude Code 等 Anthropic 原生客户端填写 https://huoxingapi.com。若客户端会自动拼接路径,请以字段提示为准,避免出现重复的 /v1/v1。
火星 API 使用 https://huoxingapi.com。先在当前网络用浏览器打开站点并发送一个最小请求;若网络异常,保留错误信息联系客服,不要自行替换成其他平台域名。
模型调用通常按实际用量结算,可能包含输入、输出、缓存、图片张数、视频时长或任务次数。具体价格和倍率以模型详情及单条使用日志为准。
进入“使用日志”,按时间、Key 或模型筛选后打开单条详情,核对输入、输出、缓存、倍率和最终费用。客户端显示值只作参考。
可能是并发请求在结算时超过剩余额度,或长请求完成后才结算。先停止新请求并核对使用日志;若记录与实际调用不符,携带请求 ID 联系客服。
账户余额、Key 自身额度、有效期、状态、分组和模型限制是分别判断的。逐项确认 Key 未停用、未过期、额度未用尽,并允许目标模型。
先用最小非流式请求判断:401 检查鉴权,402 检查余额与 Key 额度,404 检查模型 ID,连接超时检查 URL、网络和客户端超时。不要在原因不明时无限重试。
名称写清项目或软件;分组按模型与稳定性需求选择;额度和有效期按实际预算设置;模型限制非必要可留空。自动化和 Agent 建议使用较小额度的独立 Key。
确认没有多余空格、引号或重复的 Bearer;Key 未被删除或停用;启动软件的环境中读取的是新 Key。若曾公开展示,立即废弃并重建。
400 参数错误;401 鉴权失败;403 无权限或分组受限;404 路径或模型不存在;405 请求方法错误;413 请求体过大;429 速率或并发受限;500 服务异常;503 暂时不可用;504 / 524 超时。只有 429、503、504、524 适合有限次数退避重试。
可以,但不建议。按软件或项目拆分密钥,出现泄露、限额或统计问题时更容易单独处理。
不同客户端可能携带不同长度的系统提示、历史消息、工具定义和缓存字段。请以单条使用日志中的输入、输出、缓存与倍率明细为准。
桌面客户端可保存在其安全配置中;代码、服务器和自动化平台应使用环境变量或 Secret。不要放在浏览器前端、公开仓库或截图中。
接入排查、企业合作、批量用量与定制需求,都可以扫码联系客服。技术问题请一并提供请求 ID。