火星 API 火星 API · 文档
国内外模型统一接入
Huoxing API Docs

一个 API,
连接你的全部模型

从创建密钥到完成第一次请求,再到 Claude Code、Codex 与桌面客户端配置,这份文档会带你走完整个接入过程。

✓ OpenAI 兼容格式 ✓ Anthropic 原生格式 ✓ Claude · GPT · Gemini · DeepSeek · 千问 · 智谱
第一次接入只需要确认三件事

API Key、Base URL 和模型名称。不要把网页地址直接当成接口地址。

Documentation map

从这里找到全部教程

已按“新手操作、软件配置、模型接口、账户与排查”重新整理。左侧目录可逐级展开;特殊模型接口请先核对模型详情中的协议与端点。

目录已覆盖参考站的主要分类

具体能力是否可用仍以火星 API 模型广场和模型详情为准;不会把其他平台的专用端点直接写成火星 API 已支持。

Quick start

5 分钟完成第一次调用

下面以 OpenAI 兼容格式为例。复制前,请先把示例密钥和模型名称换成你控制台中的真实值。

注册并进入控制台

登录火星 API 后,在左侧进入“API 密钥”。

创建一枚独立密钥

建议为不同项目分别创建密钥,后续更容易统计、限额和停用。

选择模型并发送请求

在模型广场复制准确的模型 ID,然后用下面的请求测试。

Terminal · cURL
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"}]
  }'
!
不要公开 API Key

密钥应保存在服务端环境变量中,不要写入前端页面、公开仓库或截图。

Endpoints

先选对接入地址

不同客户端对 Base URL 的拼接方式不同。若软件会自动补全 /v1,请按软件提示填写。

O

OpenAI 兼容格式

适用于 Codex、Cherry Studio、Chatbox、OpenAI SDK 等。

https://huoxingapi.com/v1
A

Anthropic 原生格式

适用于 Claude Code 和直接调用 /v1/messages

https://huoxingapi.com
你的应用SDK / 客户端
火星 API鉴权 · 路由 · 计费
模型服务Claude / GPT / 千问…
Billing

计费、分组与倍率

模型最终费用由模型价格、实际 Token 用量和所选分组倍率共同决定。实时价格以“模型广场”和单条使用日志为准。

1

查看模型单价

确认输入、输出、缓存读取与缓存写入价格。

2

选择令牌分组

创建密钥时按稳定性、适配能力与预算选择。

3

核对使用日志

请求完成后可查看 Token 明细、倍率和最终费用。

ƒ
通用计算方式

最终费用 = 输入费用 + 输出费用 + 缓存费用,再乘以该密钥所属分组的倍率。动态计费模型以日志中实际命中的价格阶梯为准。

选择维度你需要关注建议
价格输入 / 输出 / 缓存单价与分组倍率先小额测试,再投入正式任务
稳定性延迟、成功率、上游适配重要生产任务优先稳定分组
上下文单次请求的输入 Token 数超长上下文先确认模型限制
Wallet

余额充值与账单

进入钱包

在控制台左侧点击“钱包”,或从账户概览点击“余额充值”。

选择金额并支付

按页面可用的支付方式完成充值;支付结果以钱包到账记录为准。

核对账单

充值记录与模型消费记录分开显示,便于对账。

火星 API · 钱包安全连接
账户余额
¥ 128.60
近 24 小时消费¥ 3.42
账户状态正常
余额充值
自定义充值金额¥ 100
示意图不包含真实账户数据
火星 API 原创界面示意 · 实际可用方式以控制台显示为准
Authentication

创建并管理 API Key

密钥是请求鉴权凭证。建议按“项目 / 客户端 / 环境”拆分创建,避免多人共用同一枚密钥。

火星 API · 创建新密钥控制台
创建新的 API Key
例如:生产环境 · Claude Code
请选择适合当前项目的分组
默认分组 · 日常开发与测试推荐
稳定分组 · 生产任务与长时间调用稳定
自定义分组 · 以控制台可选项为准
火星 API 原创操作示意 · 分组名称及倍率以你账户实际显示为准

一项目一密钥

方便统计消耗、设置额度和单独停用,不会影响其他项目。

只展示一次

新密钥生成后立即妥善保存;若泄露,请停用并重新创建。

Coding assistant

Claude Code 接入

Claude Code 使用 Anthropic 原生格式。Base URL 不带结尾 /v1

环境变量
ANTHROPIC_BASE_URL=https://huoxingapi.com
ANTHROPIC_AUTH_TOKEN=sk-hx-你的密钥

安装并检查 Claude Code

安装完成后运行 claude doctor 检查当前版本和运行环境;Windows 用户优先使用 WSL 或 Git Bash。

设置两项环境变量

Base URL 使用站点根地址,不要追加 /v1;密钥放入 ANTHROPIC_AUTH_TOKEN

重新打开终端并测试

进入一个测试项目运行 claude,发送一句短消息;成功后再用于正式代码仓库。

Base URLhttps://huoxingapi.com
鉴权变量ANTHROPIC_AUTH_TOKEN
请求协议Anthropic /v1/messages
i
如果客户端要求填写模型名称

请从火星 API 模型广场复制当前可用的准确模型 ID,不要根据展示名称自行猜测。

Coding assistant

Codex 接入

使用 OpenAI 兼容地址,将模型名替换为模型广场中实际可用的 GPT / Codex 模型 ID。

config.toml · 示例
model_provider = "huoxing"
model = "请填写模型ID"

[model_providers.huoxing]
name = "Huoxing API"
base_url = "https://huoxingapi.com/v1"
env_key = "OPENAI_API_KEY"

创建 Codex 专用密钥

在火星 API 控制台单独创建一枚密钥,便于设置额度、统计消耗和随时停用。

保存密钥并配置提供商

把密钥保存为 OPENAI_API_KEY,然后在 Codex 配置中添加火星 API 提供商。

从模型广场复制模型 ID

不要照搬示例模型名。先用短任务测试读取文件和输出,再用于耗时较长的工程任务。

  • 配置文件中不要直接写入真实 API Key,只引用环境变量。
  • 客户端若要求选择 Chat Completions 或 Responses,请以当前渠道明确支持的接口为准。
  • 出现 401 先检查密钥变量是否在启动 Codex 的同一个终端中生效。
!
配置字段可能随客户端版本变化

若当前 Codex 版本字段不同,以客户端自己的配置说明为准;Base URL 与密钥仍使用上面的火星 API 参数。

More coding tools

更多编程助手

下面这些工具都可以通过自定义 OpenAI 或 Anthropic 服务接入。客户端版本更新后字段名称可能变化,但核心参数一致。

编程助手 · 提供商配置火星 API 示意
Providers
HX火星 API
CCClaude Code
CXCodex
IDECursor / Cline
编辑火星 API 提供商已启用
OpenAI Compatible
从模型广场复制 ID
https://huoxingapi.com/v1
sk-hx-••••••••••••••••
测试连接保存配置
原创配置界面示意 · Claude 原生协议时 Base URL 不带 /v1

CC-Switch

分别为 Claude Code 与 Codex 创建火星 API 提供商配置,切换时选择对应协议。

Claudehttps://huoxingapi.com
Codexhttps://huoxingapi.com/v1

Cursor / Windsurf

在自定义模型或 OpenAI Base URL 中填写兼容地址,再从模型广场复制模型 ID。

Base URLhttps://huoxingapi.com/v1
</>

Cline / Roo Code

提供商选择 OpenAI Compatible;若使用 Claude 原生工具调用,则改选 Anthropic Compatible。

ClineRoo CodeOpenCode
VS

VS Code

安装支持自定义提供商的 AI 插件后,按插件协议填写火星 API;Claude Code 插件使用 Anthropic 根地址。

扩展Claude Code
KC

Kilo Code

提供商选择 OpenAI Compatible 或 Anthropic Compatible,分别使用对应 Base URL。

Agent额度保护
G

Gemini CLI

推荐通过支持 Gemini 自定义供应商的 CC-Switch 版本配置。原生 Gemini 协议是否可用以模型详情为准。

CC-SwitchGemini
TR

Trae

仅在当前插件版本提供“自定义 OpenAI / Anthropic 端点”时配置;没有该入口时不要强行替换官方登录。

OC

OpenCode

桌面端在提供商设置中新增自定义服务;CLI 可通过配置文件或 CC-Switch 管理供应商。

OpenAIhttps://huoxingapi.com/v1
MC

MiMoCode CLI

若版本支持自定义 OpenAI 兼容供应商,可复用相同参数;先用短任务验证模型和工具调用。

CD

Claude Code 桌面端

与 CLI 共用 Anthropic 配置思路;客户端若读取系统环境变量,修改后需完全退出并重新打开。

CX

Codex 桌面端

使用 OpenAI 兼容提供商和独立密钥。界面字段随版本变化时,以“Base URL / API Key / Model”三项为准。

通用排查

若能获取模型列表却无法对话,优先核对模型 ID、请求协议、流式输出和客户端超时。

模型 ID协议Timeout
CCCC-Switch 配置步骤

新增 Claude 提供商

类型选择 Claude / Anthropic,Base URL 填 https://huoxingapi.com,再填写密钥和 Claude 系列模型 ID。

新增 Codex 提供商

类型选择 OpenAI Compatible,Base URL 填 https://huoxingapi.com/v1,密钥建议与 Claude 分开创建。

分别测试再切换

先测试连接,再将当前提供商切换到火星 API。切换后重新打开对应终端,避免读取旧环境变量。

IDECursor / Windsurf 配置步骤

找到自定义模型设置

进入 Settings 中的 Models、Providers 或 API Keys;不同版本的菜单名称可能略有变化。

填写 OpenAI 兼容参数

填入火星 API Key、Base URL 和模型广场中的完整模型 ID;若软件自动补全 /v1,则按字段提示去掉重复部分。

先测试普通对话

普通对话成功后,再测试代码补全、工具调用或 Agent 模式。部分功能可能要求特定模型能力。

CRCline / Roo Code 配置步骤

选择协议

多数模型选择 OpenAI Compatible;需要 Claude 原生工具调用时选择 Anthropic Compatible。

保存连接参数

填写 Base URL、API Key、模型 ID,并根据任务规模设置最大输出和上下文限制。

控制 Agent 成本

首次使用先关闭自动批准或限制工具权限,并为这枚密钥设置额度,避免循环操作持续扣费。

VSVS Code / Kilo Code 插件

确认插件允许自定义供应商

在扩展设置中查找 Provider、API Configuration 或 OpenAI Compatible。只支持官方登录的插件不能直接填中转地址。

按协议填写地址

OpenAI 兼容用 https://huoxingapi.com/v1;Claude Code / Anthropic 兼容用 https://huoxingapi.com

先关闭自动批准

Agent 插件首次测试时关闭自动执行命令,为专用 Key 设置额度,确认工具调用正常后再逐步放开权限。

GGemini CLI + CC-Switch

安装与你系统匹配的 Gemini CLI

安装方式和 Node.js 版本以 Gemini CLI 当前官方说明为准,不在文档中固定过期的安装命令。

在 CC-Switch 选择 Gemini

新增自定义供应商,填写火星 API Key、模型 ID 和当前模型详情标注的 Gemini 兼容地址。

验证协议兼容性

若模型只标注 OpenAI 兼容,不要假定 Gemini 原生 CLI 一定可用;可改用支持 OpenAI Compatible 的编程助手。

!
Gemini 原生兼容需要单独确认

只有模型详情明确标注 Gemini 原生协议时,才能直接套用 Gemini CLI 自定义供应商配置。

OCOpenCode / Trae / MiMoCode

新增自定义提供商

优先选择 OpenAI Compatible;若目标是 Claude 原生工具调用,再选择 Anthropic Compatible。

填写三项核心参数

Base URL、API Key、完整模型 ID 缺一不可。不要复制其他平台的域名、示例密钥或模型别名。

分阶段测试

先测试普通对话,再测试读取文件、工具调用和长任务;任一步失败都保留请求 ID 后再调整。

APPClaude Code / Codex 桌面端
  • 桌面端若继承系统环境变量,修改后需要完全退出应用并重新打开。
  • Claude 使用站点根地址;Codex 和 OpenAI 兼容客户端通常使用带 /v1 的地址。
  • 桌面版和 CLI 建议使用不同 Key,便于分别限额、统计和停用。
Desktop clients

桌面客户端接入

多数桌面客户端都可选择“OpenAI 兼容”或“自定义 OpenAI”,再填写同一套参数。

自定义模型服务示意
连接参数
OpenAI 兼容
https://huoxingapi.com/v1
sk-hx-••••••••••••
模型设置
模型 ID从模型广场复制
流式输出开启
连接测试连接成功
火星 API 原创配置示意 · 不同客户端的字段名称可能略有差异
提供商类型OpenAI Compatible
Base URLhttps://huoxingapi.com/v1
模型名称从模型广场复制完整 ID
CSCherry Studio

新增自定义服务商

在模型服务设置中选择新增服务商,协议选择 OpenAI 或 OpenAI Compatible。

填入三项核心参数

填写火星 API Key、Base URL 和模型 ID,启用该服务商后保存。

检查并开始对话

先执行连接检查或获取模型,再新建一个短对话。若提示模型不存在,请重新复制完整 ID。

CBChatbox

打开模型提供方设置

新增自定义提供方,兼容类型选择 OpenAI API。

填写地址与密钥

Base URL 填 https://huoxingapi.com/v1,再填入专用密钥。

手动添加模型

如果没有自动列出模型,就把模型广场中的模型 ID 手动添加到可选列表。

NCNextChat / LobeChat

确认使用方式

本地桌面版可在设置中填写;自己部署的版本通常需要在服务端环境变量或供应商配置中填写。

不要把密钥写进前端

公开部署时必须由服务端读取密钥,避免浏览器源码或网络请求泄露主账户凭证。

保存后重启自部署服务

环境变量变更一般要重启对应容器或服务;正式操作前先查看当前版本说明。

WBWorkBuddy

查找自定义模型入口

在模型服务或供应商设置中确认当前版本是否提供 OpenAI Compatible。没有自定义端点入口时无法直接接入。

填写连接参数

使用 https://huoxingapi.com/v1、专用 API Key 和模型广场中的完整模型 ID。

用空白会话验证

先测试一句短消息,再启用知识库、附件或工具调用;不同能力需要模型本身支持。

ST酒馆 / OpenClaw

选择自定义 OpenAI 端点

不要选择官方账号登录,改用自定义 API / OpenAI Compatible 配置。

填写模型与上下文

模型 ID 必须与模型广场一致;上下文上限不要盲目设得过大,以免单次请求费用异常。

用新会话测试

旧会话可能携带很长历史记录。首次测试请新建空白会话,确认正常后再导入角色卡和知识库。

Workflows & automation

工作流与自动化工具

只要工具支持自定义 OpenAI 服务,通常都可以接入。生产工作流建议设置请求超时、重试上限和单任务费用保护。

AI 工作流 · 模型节点Dify / n8n 通用示意
客户咨询自动回复草稿已保存
用户输入接收问题
火星 API 模型OpenAI 兼容
生成回复保存结果
原创工作流示意 · 自动化任务建议单独创建密钥与额度
D

Dify

在模型供应商中使用 OpenAI-API-compatible 类型,填写火星 API Base URL、密钥与模型 ID。

Base URLhttps://huoxingapi.com/v1
N8

n8n

优先使用允许自定义 Base URL 的 OpenAI 节点;没有该字段时改用 HTTP Request。

Endpoint/v1/chat/completions
CZ

Coze / 扣子

根据当前版本选择自定义模型或 HTTP 节点,并确认密钥不会暴露到客户端。

FG

FastGPT

配置 OpenAI 兼容模型供应商;知识库应用还需区分聊天模型与嵌入模型 ID。

重试策略

对 429、502、503、504 使用有限次数的指数退避;不要对鉴权或余额错误无限重试。

¥

费用保护

为自动化任务单独创建密钥和额度,避免异常循环调用消耗主账户余额。

DDify 模型供应商配置

打开模型供应商页面

在工作区设置中找到模型供应商,选择 OpenAI-API-compatible 或当前版本提供的自定义 OpenAI 插件。

添加模型凭证

填写 Base URL、API Key 和模型 ID;模型类型按实际能力选择聊天、推理或嵌入。

在测试应用中验证

先建立只有“开始—模型—结束”的最小工作流,成功后再加入知识库、工具和循环节点。

KEYCC-Switch 导入火星 API Key

先在控制台创建专用 Key

按 Claude、Codex 或 Gemini 用途分别创建,设置分组、额度和有效期,不要导入主账户长期密钥。

新增对应协议的供应商

Claude 选 Anthropic 根地址;Codex 选 OpenAI Compatible 并填写带 /v1 的地址。

测试成功后再设为当前

确认连接、模型 ID 和短对话成功,再切换供应商并重新打开终端。

DSClaude Code + CC-Switch 使用 DeepSeek / GLM
  • 只有当前通道明确提供 Claude Code / Anthropic 协议转换时才能这样使用。
  • 模型 ID 从火星 API 模型广场复制,不能把 Claude 示例模型名直接替换成展示名称。
  • 国产模型的工具调用、思考字段和上下文行为可能与 Claude 不完全一致,先用小项目测试。
N8n8n 接入

优先检查 OpenAI 节点

如果当前版本允许自定义 Base URL,可直接创建凭证并填写火星 API 参数。

没有 Base URL 就用 HTTP Request

/v1/chat/completions 发送 POST,请求头包含 Bearer 密钥和 JSON 内容类型。

限制重试次数

只对 429、502、503、504 做有限重试;401、402、404 应直接停止并记录错误。

CFCoze / FastGPT

选择自定义模型或 HTTP 节点

能添加 OpenAI 兼容供应商时直接添加;若平台版本不提供该入口,则使用 HTTP 请求节点。

映射输入与输出

把用户问题写入 messages,再从响应中的助手文本字段读取结果。

上线前设置费用保护

单独创建令牌、设置额度并限制循环次数;批量工作流先用少量数据验证。

Open source & infrastructure

开源项目与高级部署

OpenWebUIOpenAI 兼容地址与独立密钥
通用
LibreChat自定义 OpenAI Endpoint
通用
OpenClawWeb / Linux · 自定义模型端点
部署
Hermes AgentCLI · 环境变量或供应商配置
Agent
Pi Coding AgentOpenAI Compatible · 专用 Key
编程
Docker / Compose通过环境变量注入密钥
部署
CI / Serverless使用平台 Secret 管理密钥
安全
.env · 通用示例
OPENAI_API_KEY=sk-hx-你的密钥
OPENAI_BASE_URL=https://huoxingapi.com/v1
MODEL_NAME=请填写模型ID

为部署创建专用密钥

不要复用管理员或个人测试密钥;设置合理额度,并在备注中标明项目和环境。

通过 Secret 注入

把密钥保存到平台 Secret、容器环境变量或安全配置中心,不提交到 Git 仓库。

发布前做健康检查

先验证模型列表或发送短请求,再开放给用户;保留请求 ID、状态码和响应时间用于排查。

OCOpenClaw Web 界面

进入模型供应商设置

选择自定义 OpenAI 兼容供应商,填写 https://huoxingapi.com/v1、专用 Key 和模型 ID。

检查上下文上限

不要照搬其他模型的超长上下文设置;先以模型详情和小额测试为准。

先验证网页对话

对话正常后再接入 QQ、Telegram 等外部机器人,避免同时排查模型和消息通道。

LXOpenClaw Linux / 云服务器
  • 把 API Key 放入服务端环境变量或 Secret,不写进镜像、公开仓库和启动日志。
  • 更新配置后仅重启 OpenClaw 对应服务或容器;不要为了改文档或密钥重启整台服务器。
  • 开放公网前设置访问认证、请求超时、并发限制和单项目额度。
HAHermes Agent / Pi Coding Agent
协议OpenAI Compatible
Base URLhttps://huoxingapi.com/v1
模型从模型广场复制 ID

若当前版本仅支持官方账号登录或固定供应商,则不能直接接入;不要修改程序源码绕过鉴权。

UIOpenWebUI / LibreChat
  • OpenWebUI 通常在 Connections / OpenAI API 中添加 URL 与 Key。
  • LibreChat 使用自定义 OpenAI Endpoint 时,密钥应保存在服务端配置或 Secret。
  • 多人使用时不要让所有用户共用无限额度 Key;按项目拆分并设置限额。
!
环境变量名称以项目自身为准

有的项目使用 OPENAI_API_BASEOPENAI_BASE_URL 或供应商专用字段。先查看该项目的示例配置,避免填错后反复重启。

API reference

OpenAI 兼容接口

适用于 OpenAI SDK 及支持自定义 Base URL 的客户端。请求路径通常为 /v1/chat/completions

JavaScript
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: "你好" }],
});
Python
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限制最大输出;具体字段兼容性以模型详情为准

能力与端点目录

下面用于帮助客户选接口,不代表每个模型都支持全部能力。先在模型广场确认模型能力和端点,再按对应格式调用。

文本生成 / 对话POST /v1/chat/completions通用
使用 messages 传入对话;先用非流式请求联调,成功后再启用 stream。
长上下文阅读POST /v1/chat/completions看模型
上下文上限由具体模型决定。历史消息、工具结果和附件文本都会计入输入用量。
图片理解chat.completions · 多模态 content看模型
仅对视觉模型使用;图片可用 URL 或模型明确接受的 Base64 形式,注意大小和格式限制。
图片生成与编辑/v1/images/generations · /v1/images/edits看模型
模型详情若提供专用异步端点,应优先使用专用协议,不要把所有图片模型都套进同一路径。
函数调用 / Toolstools · tool_choice看模型
客户端负责执行工具并把结果回传模型。首次测试不要自动批准高风险命令。
Responses APIPOST /v1/responses看渠道
只有模型或渠道明确标注支持时使用;否则继续使用 Chat Completions。
文本嵌入 / EmbeddingsPOST /v1/embeddings看模型
聊天模型不能直接当嵌入模型。知识库应用需单独选择嵌入模型并确认向量维度。
音频、TTS 与转录/v1/audio/speech · transcriptions · translations看模型
音频格式、文件大小、语言和响应类型由模型决定;长文件先切分并测试一小段。
文件与 PDF 分析文件上传或多模态消息看协议
有的模型使用文件接口,有的需要先提取文本或传入 URL。以模型详情的示例为准。
i
先用非流式请求完成联调

确认鉴权、模型和返回格式正常后再启用流式输出,更容易区分接口问题与客户端流解析问题。

API reference

Anthropic 原生接口

请求使用 x-api-keyanthropic-version 请求头,路径为 /v1/messages

Terminal · cURL
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/messages
鉴权请求头x-api-key: 你的密钥
协议版本anthropic-version: 2023-06-01
原生文本生成POST /v1/messages通用
必填 model、max_tokens 与 messages;系统提示词使用 system 字段。
思考配置thinking / budget_tokens看模型
思考字段和预算需要模型与渠道支持,不要把其他模型的思考参数直接照搬。
图片理解content: image + text看模型
图片放在消息内容数组中;确认 MIME 类型、Base64 大小和模型视觉能力。
函数调用 / Toolstools · tool_use · tool_result看模型
工具结果必须带回与 tool_use 对应的 ID;客户端中断时不要无限自动重试。
OpenAI 兼容格式POST /v1/chat/completions看分组
适合只支持 OpenAI 协议的客户端;Claude Code 本身优先使用 Anthropic 原生接口。
  • Claude Code 的 Base URL 填站点根地址;直接调用接口时请求路径仍是 /v1/messages
  • 输出上限、工具调用和多模态字段必须由所选模型支持,不能只看系列名称。
  • 如果错误日志显示 client_gone,先排查客户端超时或主动取消,不要立即无限重试。
Google models

Google / Gemini 接入

优先使用 OpenAI 兼容格式接入 Gemini,这样能复用现有 SDK 和客户端。模型名称请从模型广场复制。

统一接口 · 模型路由火星 API
选择模型系列
Gemini · 多模态
DeepSeek · 推理
Qwen / GLM · 国产模型
统一 OpenAI 兼容请求
POST /v1/chat/completions
{
  "model": "模型广场中的 ID",
  "messages": [...]
}
原创协议示意 · 不同模型可以复用同一套鉴权与请求结构
G

OpenAI 兼容调用

适合聊天、编程和多数第三方客户端。

Base URLhttps://huoxingapi.com/v1
β

Google 原生格式

仅在模型详情明确标注支持时使用;请求路径、版本与多模态字段以该模型说明为准。

Gemini多模态原生协议
OpenAI 兼容接口POST /v1/chat/completions推荐
第三方客户端优先使用此格式,Base URL 填 https://huoxingapi.com/v1
Gemini 原生接口generateContent / streamGenerateContent看渠道
路径和版本随兼容层不同,只有模型详情明确提供示例时使用。
思考与推理模型专用 thinking 参数看模型
不同系列的思考预算字段不完全相同,必须参考当前模型说明。
图片理解多模态消息 / inline data看模型
支持的图片格式、大小和张数以视觉模型详情为准。
图片生成与编辑Imagen / Nano Banana 等专用协议看模型
文生图、图生图和编辑可能使用不同端点,不能只替换模型名。
音频理解音频输入 + 文本指令看模型
长音频先确认时长、文件大小和支持的编码格式。
视频理解视频输入 / 文件引用看模型
视频理解与视频生成不是同一能力;不要把 Veo 任务端点当作 Gemini 分析端点。
文字转语音TTS / audio output看模型
音色、语言、格式和返回方式由模型决定,批量生成前先用短文本验证。
!
不要把模型展示名当作模型 ID

同一系列可能包含不同日期、上下文和多模态版本,必须复制模型广场中的完整 ID。

China models

国产模型统一接入

DeepSeek、通义千问、智谱 GLM 与豆包等模型可在同一 OpenAI 兼容地址下调用,实际可用型号以模型广场为准。

DeepSeek对话 · 推理 · 编程
兼容
通义千问 Qwen文本 · 视觉 · 编程
兼容
智谱 GLM文本 · 工具调用
兼容
豆包以模型广场可用型号为准
兼容
国产模型 · 通用请求
curl https://huoxingapi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-hx-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"从模型广场复制ID","messages":[{"role":"user","content":"你好"}]}'
Media generation

图像、视频、音频与 3D

多媒体模型的任务提交、状态查询和结果字段差异较大。火星 API 会在模型详情中标注具体协议;未标注前不要直接套用文本接口。

多媒体任务中心生成结果示意
图像生成FLUX · 文生图
视频生成Sora · Veo
音乐生成Suno · 音频
3D
三维模型Text / Image to 3D
原创结果类型示意 · 具体任务参数和文件格式以模型详情为准
MJ

Midjourney

可能提供 Imagine、Blend、Action、Describe、Edit、Video 等能力;具体端点以模型详情为准。

FX

FLUX

文生图、参考图与编辑可能使用 OpenAI 图片格式或专用任务协议,不能只替换模型名。

SD

Stable Diffusion

确认尺寸、步数、负面提示词、种子和图片返回格式是否由当前通道支持。

ID

Ideogram

适合文字排版类图片时仍要以模型详情中的参数和协议为准。

RC

Recraft

确认输出格式、尺寸和风格参数;批量生成前先测试最低规格。

DB

豆包 Seedream

区分文生图、单图编辑和多图参考,使用模型详情给出的准确模型 ID。

ED

图生图与图片编辑

注意 multipart、图片 URL、Base64 三种输入方式不能混用。

视频接口总览

视频通常为异步任务:提交后保存任务 ID,再查询状态直至成功或失败。

SO

Sora

官方异步、渠道异步和兼容格式可能并存;创建、查询、下载必须使用同一套协议。

VE

Veo

区分文生视频、图生视频和状态查询;时长、比例、分辨率都会影响费用。

ID

视频任务与查询

保存任务 ID,使用合理轮询间隔;失败、取消或完成后立即停止查询。

音频接口总览

生成、歌词、分离和查询任务可能是不同端点。

SU

Suno 音乐

关注歌词、风格、时长、是否纯音乐及结果文件的有效期。

ST

人声 / 伴奏分离

先确认输入音频来源、支持格式以及结果文件的版权和保存期限。

音频任务查询

批量和单任务查询路径可能不同;不要高频轮询。

3D

3D 模型

常见流程为图片或文字生成任务、轮询状态并下载模型文件。

接口类型调用前确认日志中保留
图像模型 ID、尺寸、张数、参考图格式请求 ID 与图片任务 ID
视频分辨率、时长、宽高比、异步查询路径任务 ID 与失败原因
音频歌词、风格、时长与版权使用范围任务 ID 与结果 URL
3D输入格式、输出格式与文件大小任务 ID 与下载有效期

先确认模型协议

在模型详情中确认是同步返回、异步任务还是 OpenAI 兼容接口,并复制准确的请求路径。

提交任务并保存任务 ID

异步模型提交成功不等于生成完成。必须保存任务 ID,作为后续查询、计费和客服排查依据。

有限次数查询状态

按合理间隔查询,遇到失败状态立即停止;不要每秒高频轮询或对永久失败任务持续重试。

及时下载结果

生成文件 URL 可能有有效期。下载完成后保存到自己的存储,并记录内容授权与使用范围。

!
多媒体计费不一定只按 Token

图片张数、分辨率、视频时长、音频长度或任务次数都可能影响费用。正式批量生成前先用最低规格测试一笔。

Personal API & account

个人账户、令牌与统计

目前推荐从控制台完成账户与令牌操作。控制台内部接口可能随版本变化,不建议第三方程序直接依赖未公开的后台路径。

使用日志 · 费用核对控制台示意
请求 ID模型Token费用状态
hx_8F2A…Claude 系列12,840¥0.186成功
hx_30BC…GPT 系列4,216¥0.042成功
hx_A19E…Gemini 系列0¥0.000失败
原创日志界面示意 · 数值仅用于演示,不代表实际价格

账户信息

查看用户名、账户状态、余额与个人资料;不要在公开截图中展示隐私信息。

令牌管理

创建、停用、删除密钥,按项目设置分组与额度;密钥明文只安全保存一次。

日志与统计

按时间、用户、令牌、模型和状态筛选,核对输入输出 Token、缓存与最终费用。

钱包与账单

查看充值记录和消费明细。对账时以单条请求 ID 与钱包流水为依据。

导出与对账

当前控制台若提供导出功能,可按时间和密钥导出;没有导出入口时先用筛选结果逐条核对。

按时间与密钥缩小范围

先选择异常发生的时间段,再按用户名、令牌或模型过滤,避免在大量日志中手工翻找。

打开单条请求详情

核对请求 ID、上游请求 ID、输入输出 Token、缓存读取与写入、倍率、状态和最终费用。

关联上下游记录

优先使用上游请求 ID 对账;没有上游 ID 时保留本地请求 ID、时间、渠道和结束原因。

处理异常扣费

不要只看输入 Token 估算。先确认上游是否真实接收、是否产生缓存费用,再决定退款或修正规则。

i
后续公开个人 REST API 时再补充请求示例

在接口正式公开前,文档不会编造获取余额、创建密钥或查询日志的路径。

Troubleshooting

常见错误与排查顺序

现象常见原因先这样处理
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 和参数错误应先修正配置。

!
联系技术支持时请保留请求 ID

不要发送完整 API Key。提供时间、模型、请求 ID、错误信息与能否复现即可。

FAQ

常见问题

入门必看

如何充值?

进入控制台的“钱包”,选择充值金额并按页面提示完成支付。到账情况以钱包余额和充值记录为准;未到账时保留支付时间与订单信息联系客服。

可以使用哪些模型?

以火星 API“模型广场”当前展示为准,涵盖 Claude、GPT、Gemini、DeepSeek、通义千问、智谱 GLM 等系列。模型会更新或调整,不在文档中固定一份容易过期的型号清单。

API Key 在哪里获取?

登录控制台,进入“API 密钥”后创建。火星 API 的一枚 Key 可按其分组调用多个模型,不需要分别获取官方 OpenAI、Claude 或 Gemini Key。

怎么更换模型?

在模型广场复制新的完整模型 ID,并替换请求中的 model。如果新模型属于不同分组或协议,还要确认当前 Key 的分组和客户端协议是否兼容。

Base URL 到底要不要带 /v1?

OpenAI 兼容客户端通常填写 https://huoxingapi.com/v1;Claude Code 等 Anthropic 原生客户端填写 https://huoxingapi.com。若客户端会自动拼接路径,请以字段提示为准,避免出现重复的 /v1/v1

中国大陆网络能使用吗?

火星 API 使用 https://huoxingapi.com。先在当前网络用浏览器打开站点并发送一个最小请求;若网络异常,保留错误信息联系客服,不要自行替换成其他平台域名。

按量计费还是按月支付?

模型调用通常按实际用量结算,可能包含输入、输出、缓存、图片张数、视频时长或任务次数。具体价格和倍率以模型详情及单条使用日志为准。

怎么看一次调用消耗了多少 Token?

进入“使用日志”,按时间、Key 或模型筛选后打开单条详情,核对输入、输出、缓存、倍率和最终费用。客户端显示值只作参考。

余额为什么可能显示为负?

可能是并发请求在结算时超过剩余额度,或长请求完成后才结算。先停止新请求并核对使用日志;若记录与实际调用不符,携带请求 ID 联系客服。

常见误区

明明有余额,为什么 Key 仍不能用?

账户余额、Key 自身额度、有效期、状态、分组和模型限制是分别判断的。逐项确认 Key 未停用、未过期、额度未用尽,并允许目标模型。

Key 为什么不能用,调用为什么没有反应?

先用最小非流式请求判断:401 检查鉴权,402 检查余额与 Key 额度,404 检查模型 ID,连接超时检查 URL、网络和客户端超时。不要在原因不明时无限重试。

新建 Key 的参数怎么填?

名称写清项目或软件;分组按模型与稳定性需求选择;额度和有效期按实际预算设置;模型限制非必要可留空。自动化和 Agent 建议使用较小额度的独立 Key。

为什么提示“无效令牌”?

确认没有多余空格、引号或重复的 Bearer;Key 未被删除或停用;启动软件的环境中读取的是新 Key。若曾公开展示,立即废弃并重建。

400、401、403、404、405、413、429、500、503、504、524 分别怎么处理?

400 参数错误;401 鉴权失败;403 无权限或分组受限;404 路径或模型不存在;405 请求方法错误;413 请求体过大;429 速率或并发受限;500 服务异常;503 暂时不可用;504 / 524 超时。只有 429、503、504、524 适合有限次数退避重试。

安全与费用

一个 API Key 能否给多个软件使用?

可以,但不建议。按软件或项目拆分密钥,出现泄露、限额或统计问题时更容易单独处理。

为什么同一个请求在不同客户端费用不一样?

不同客户端可能携带不同长度的系统提示、历史消息、工具定义和缓存字段。请以单条使用日志中的输入、输出、缓存与倍率明细为准。

应该把 API Key 放在哪里?

桌面客户端可保存在其安全配置中;代码、服务器和自动化平台应使用环境变量或 Secret。不要放在浏览器前端、公开仓库或截图中。

Support & Business

还有问题?联系火星 API

接入排查、企业合作、批量用量与定制需求,都可以扫码联系客服。技术问题请一并提供请求 ID。

接入支持企业合作问题排查
火星 API 客服二维码
已复制