APIMart API 怎么调用？从 API Key 到首次请求
简答：APIMart API 的最短调用路径是：准备可用的 API Key，使用文档展示的 OpenAI 兼容 Base URL，再向对应的聊天端点发送包含 model 和 messages 的 JSON 请求。首次测试建议先用 curl；如果返回包含 choices 或等价结果字段的成功响应，说明 Key、地址、模型 ID 和请求格式基本匹配。本文只讲 API 配置与调用方法，不提供注册、登录或充值入口。
定义：APIMart API 调用，是通过 API Key、Base URL、模型 ID 和符合接口要求的请求体，向兼容接口或 MCP 端点发送 HTTP 请求并读取返回结果。
先复制这 3 步：完成一次最小调用
截至 2026-10-31 核验，公开文档展示的 OpenAI 兼容调用方式可以概括为以下三步。由于模型、接口状态和认证规则可能变化，实际接入前仍应以当前模型详情页和文档为准。
- 准备 Key：从你自行核验的 APIMart 账户控制台创建或复制 API Key，不要把真实密钥写入代码仓库、截图或前端页面。
- 配置地址：文档示例使用
https://api.apimart.ai/v1作为 OpenAI 兼容 Base URL，聊天请求地址是在其后拼接/chat/completions。该地址属于来源页面展示的示例，使用前请再次核对当前文档。 - 发送请求：请求头放入
Authorization: Bearer 你的Key，请求体至少包含当前可用的model和messages。
来源页面给出的最小 curl 结构如下，示例中的 Key 和模型 ID 必须替换为你自己的实际值：
curl https://api.apimart.ai/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer sk-xxxxxxxxxxxx" -d '{"model":"你的模型ID","messages":[{"role":"user","content":"你好，请用一句话介绍自己"}]}'
成功判定不要只看 HTTP 状态码。对于聊天接口，应继续检查响应是否包含可读取的结果字段，例如 choices 或当前接口文档规定的等价字段；如果返回 HTML、纯文本错误页或空响应，应按错误分流处理，而不是直接当作模型结果。
以上请求格式、请求地址和 Bearer 认证写法可对照 APIMart 文档中的 Gemini CLI 与代码调用示例。
调用前要准备什么：Key、余额与模型 ID
如果你还没有成功调用过，建议按下面的顺序检查，而不要一开始就反复更换模型或 SDK。
- API Key：确认复制的是完整密钥，没有前后空格、换行或被错误截断。密钥应通过环境变量传入，例如 Bash 可使用
export APIMART_API_KEY="你的Key"，PowerShell 可使用$env:APIMART_API_KEY = "你的Key"。 - 余额或可用额度：部分调用可能需要账户中存在可用额度。是否需要购买点数、当前余额和具体扣费规则，应以账户页面和当前文档为准，本文不提供充值入口，也不对动态价格作判断。
- 模型 ID：模型展示名不一定等于请求字段中的 ID。应从当前模型详情页或 API 文档复制精确的
model值，不要凭名称猜测。 - 接口类型：聊天、图像、视频和 MCP 不是同一套请求格式。本文的主要示例是同步的 OpenAI 兼容聊天请求；图像、视频等模型若采用任务提交与查询机制，必须按照对应模型文档中的请求体和查询端点执行。
公开入门文档将流程拆分为创建账户、购买点数、创建 API 密钥和首次调用，并说明直接 HTTP 与 MCP 客户端是两条不同路径，可参考 Getting started 入门文档。本文不替读者判断具体账户状态，也不把该页面中的动态价格或套餐信息当作长期固定规则。
curl、Python 和 JavaScript 怎么写
curl：最适合第一次验证
先用 curl 是因为它能绕开 SDK 版本、环境变量命名和客户端默认路径等干扰。建议先把模型 ID 替换好，再运行下面的结构：
curl "$APIMART_BASE_URL/chat/completions" -H "Content-Type: application/json" -H "Authorization: Bearer $APIMART_API_KEY" -d '{"model":"你的模型ID","messages":[{"role":"user","content":"只返回：调用成功"}]}'
其中 APIMART_BASE_URL 可先设置为文档示例中的 https://api.apimart.ai/v1。如果返回成功，再迁移到 SDK；如果 curl 已失败，优先检查地址、Key、模型 ID 和响应体。
Python：使用新版 OpenAI 客户端写法
如果使用新版 OpenAI Python SDK，可采用客户端对象和 base_url 参数：
from openai import OpenAI
import os
client = OpenAI(api_key=os.environ["APIMART_API_KEY"], base_url=os.environ.get("APIMART_BASE_URL", "https://api.apimart.ai/v1"))
response = client.chat.completions.create(model="你的模型ID", messages=[{"role": "user", "content": "请返回一句测试文本"}])
print(response.choices[0].message.content)
如果 SDK 报参数不兼容，先确认安装的 OpenAI SDK 版本和当前文档示例是否匹配。不要把旧版 openai.ChatCompletion.create 写法与新版客户端对象写法混用。
JavaScript/TypeScript：检查 baseURL 是否被覆盖
Node.js 项目可以使用 OpenAI 客户端对象：
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.APIMART_API_KEY,
baseURL: process.env.APIMART_BASE_URL || "https://api.apimart.ai/v1",
});
const result = await client.chat.completions.create({
model: "你的模型ID",
messages: [{ role: "user", content: "请返回一句测试文本" }],
});
console.log(result.choices?.[0]?.message?.content ?? result);
服务端代码才适合保存 API Key。不要把密钥放进浏览器端打包文件、公开仓库或前端请求中。
OpenAI 兼容 API 和 MCP，应该选哪一种
两种方式都可以发起调用，但解决的问题不同。不要把 MCP 地址当成聊天 API 的 Base URL，也不要把 OpenAI 兼容请求体直接发送到 MCP 端点。
| 接入方式 | 适合场景 | 认证与请求特点 | 首次验证建议 |
|---|---|---|---|
| OpenAI 兼容 API | 已有 Python、JavaScript、curl 或支持 OpenAI 格式的应用 | 通常使用 Base URL、Bearer Key，以及聊天接口规定的 JSON 请求体 | 先测试 /chat/completions 的最小请求 |
| MCP | 需要让支持 MCP 的客户端发现、查询并调用工具 | 使用 MCP 端点、JSON-RPC 方法和工具参数，具体传输方式以当前文档为准 | 先调用 tools/list 或文档规定的发现方法 |
| 图像或视频任务 | 需要生成图片、视频或执行异步任务 | 请求体、返回字段和任务查询端点由具体模型文档决定 | 先确认提交接口、状态字段和结果字段，不套用聊天接口 |
公开入门文档展示了 MCP 的 Streamable HTTP 与 JSON-RPC 请求结构，例如 tools/list 和 tools/call。如果你的目标只是让程序返回一段文本，优先从 OpenAI 兼容接口开始；如果目标是让客户端发现并调用目录中的工具，再研究 MCP 配置。
401、403、404、429 和超时怎么排查
排错固定按照“实际请求地址—认证—模型—请求体—响应体”的顺序进行。以下是通用分流，不代表某个平台对每个状态码只有一种原因；最终应以实际响应、控制台记录和当前文档为准。
| 现象 | 先检查什么 | 下一步 |
|---|---|---|
401 Unauthorized | Bearer 拼写、Key 是否完整、环境变量是否加载、是否误用了 MCP Key 或其他服务的 Key | 打印脱敏后的 Key 前缀和实际 Base URL，重新发送最小 curl 请求 |
403 Forbidden | 当前 Key、账户权限、模型可用性和接口类型 | 查看响应体，不要仅凭状态码推断地区、余额或套餐原因 |
404 Not Found | Base URL 是否重复拼接 /v1、路径是否写成当前接口要求、模型接口是否与聊天接口不同 | 记录 SDK 最终请求地址，确认没有出现 /v1/v1 或错误端点 |
429 Too Many Requests | 请求频率、并发量、账户额度和响应头中的重试提示 | 降低并发，使用带上限的指数退避；不要无间隔无限重试 |
| 连接超时或空响应 | 域名解析、网络连接、客户端超时设置、请求是否实际到达服务端 | 先用最小请求测试，再区分同步请求超时与异步任务查询 |
日志中只保留必要的诊断信息，例如状态码、请求路径、模型 ID、耗时和脱敏后的 Key 前缀；不要记录完整 API Key、完整 Authorization 请求头或可能包含隐私的提示词。
首次调用成功后，如何确认配置真的生效
- 确认响应不是 HTML 错误页，并能解析为预期 JSON 或当前接口规定的响应格式。
- 确认结果字段中有实际文本、图片任务 ID 或当前模型文档规定的结果字段。
- 在控制台或当前文档提供的用量记录中核对是否出现对应请求；动态用量和扣费信息以账户页面为准。
- 将 API Key 从代码中移到环境变量，并把
.env加入.gitignore。 - 如果更换模型，重新核对模型 ID、输入格式、同步或异步模式，不要只替换
model字符串。
达到这五项后，才适合把测试代码迁移到业务服务。生产环境还应增加超时、有限重试、并发控制、错误日志脱敏和密钥轮换。
常见问题
APIMart API 调用一定要使用 OpenAI SDK 吗？
不一定。只要客户端能够发送 HTTP 请求，就可以使用 curl、Python、JavaScript 或其他语言。OpenAI SDK 只是便于复用 OpenAI 兼容的客户端结构；如果遇到 SDK 版本或参数问题，可以先用 curl 验证 Key、Base URL、模型 ID 和请求体。
Base URL 应该填什么？需要加 /chat/completions 吗？
公开文档示例使用 https://api.apimart.ai/v1 作为 OpenAI 兼容 Base URL，聊天请求再使用 /chat/completions 路径。SDK 的 base_url 通常填前者，curl 直接请求时才拼接完整路径。实际地址可能随文档调整，使用前应核对当前来源页面。
为什么 API Key 正确，仍然返回 401？
先检查实际请求是否带有 Authorization: Bearer 头，Key 是否被环境变量正确加载，是否包含空格或换行，以及 Base URL 是否指向了正确接口。还要确认没有把 MCP 端点使用的密钥格式和 OpenAI 兼容接口混用。建议用最小 curl 请求复现，并查看脱敏后的实际请求地址。
调用图像或视频模型可以直接套用 chat/completions 吗？
不能默认套用。图像和视频模型可能使用不同请求体、返回结构或异步任务流程。应先查看对应模型文档，确认提交接口、参数、任务状态字段和结果查询端点；未核实的固定任务地址不要直接写进代码。
MCP 和 OpenAI 兼容 API 有什么区别？
OpenAI 兼容 API 更适合程序直接发送聊天请求，核心是 Base URL、Bearer Key、模型 ID 和 JSON 请求体。MCP 更适合支持 MCP 的客户端发现并调用工具，通常涉及 MCP 端点、JSON-RPC 方法和工具参数。两者的端点和请求格式不能混用。
相关阅读
- 先看 APIMart API Key、环境变量与 Base URL 配置
- 继续了解 APIMart OpenAI 兼容接口的接入方式
- 如果返回 401，可按 Key、Bearer 和地址逐项排查
- 遇到 429 时查看限流、配额与重试处理
- 请求超时可继续看连接诊断与异步处理方法
参考资料
- APIMart 文档：在 Gemini CLI 中使用 APIMart（docs.apimart.ai）
- apimart docs：Getting started 入门文档（apimart.app）