Oimi APIOimi API 文档

入门指南

从登录控制台、创建密钥到查看用量，完成 Oimi API 的基础接入。

入门指南

本指南会带你完成 Oimi API 的基础接入流程。完成后，你将能够创建 API 密钥、选择可用模型、在体验中心测试请求，并在自己的应用中调用接口。

1. 登录控制台

打开平台首页，进入登录或注册页面。账号创建完成后，进入控制台首页。

控制台首页会展示账户余额、请求量、用量概览、快速开始示例、API 访问信息和最近调用记录。这里适合确认当前服务地址、账户状态和最近请求是否正常。

2. 创建 API 密钥

进入「控制台 / API 密钥」，点击「创建 API 密钥」。

创建时只需要填写备注，用来区分这个密钥的用途，例如 生产环境应用、测试环境 或某个项目名称。

创建成功后请立即复制完整密钥。关闭创建弹窗后，完整密钥不会再次显示。

在「API 密钥」页面，你可以继续管理已有密钥：

  • 启用或禁用密钥
  • 删除不再使用的密钥
  • 调整密钥额度
  • 切换模型变体
  • 查看密钥备注、状态和使用情况

3. 选择模型

进入「模型」页面，可以查看当前账号可用的模型列表。模型列表会展示模型 ID、输入价格、输出价格、缓存读写价格、模型变体和倍率信息。

接入应用时，请直接使用「模型」页面展示的模型 ID。不同账号或不同模型变体可见的模型可能不同，实际可调用范围以当前控制台展示为准。

4. 使用体验中心调试

进入「体验中心」，选择模型和 API 密钥后即可发起测试请求。

体验中心适合在正式接入前验证模型行为、参数效果和密钥权限。你可以在这里：

  • 选择模型
  • 选择 API 密钥
  • 设置 system/user/assistant 消息
  • 调整 temperature、top_p、max_tokens 等参数
  • 开启或关闭流式输出
  • 查看请求结果和错误信息

5. 在应用中接入

如果你的应用已经使用 OpenAI SDK，通常只需要替换 base_url 和 api_key。

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.OIMI_API_KEY,
  baseURL: 'https://api.oimi.xin/v1'
})

const completion = await client.chat.completions.create({
  model: 'model-id',
  messages: [{ role: 'user', content: '写一个上线检查清单' }]
})

console.log(completion.choices[0].message.content)

请将 model-id 替换为「模型」页面中的实际模型 ID。API 密钥建议只保存在服务端环境变量中，不要放在浏览器前端代码或公开仓库里。

6. 常用客户端接入

在配置 Codex、Claude Code、OpenCode、Gemini 或 CC-Switch 前，先准备好这几项信息：

  • 服务地址：https://api.oimi.xin
  • OpenAI 兼容服务地址：https://api.oimi.xin/v1
  • API 密钥：在「API 密钥」页面创建，创建后立即复制保存
  • 模型 ID：在「模型」页面复制实际可用的模型 ID
  • 验证入口：先在「体验中心」用同一个 API 密钥和模型测试一次

下方示例统一使用 model-id 作为占位。接入时请替换为「模型」页面展示的实际模型 ID。

Codex

Codex 适合在终端或 Codex 桌面应用里处理代码任务。接入 Oimi API 的核心是给 Codex 增加一个自定义模型提供方。

建议把配置写到用户级配置文件，这样不同项目都能使用同一套 Oimi API 配置：

  • Windows：C:\Users\<用户名>\.codex\config.toml
  • macOS / Linux：~/.codex/config.toml

在配置文件中加入：

model = "model-id"
model_provider = "oimi"

[model_providers.oimi]
name = "Oimi API"
base_url = "https://api.oimi.xin/v1"
env_key = "OIMI_API_KEY"
wire_api = "chat"

然后在终端设置 API 密钥。

Windows PowerShell：

$env:OIMI_API_KEY="你的 Oimi API 密钥"
codex

macOS / Linux：

export OIMI_API_KEY="你的 Oimi API 密钥"
codex

如果只想临时指定某个模型，可以启动时传入模型 ID：

codex -m model-id

如果你不确定模型应该使用哪种协议，先保持 wire_api = "chat"。只有在确认当前模型和客户端需要 Responses 协议时，再改为 wire_api = "responses"。

Claude Code

Claude Code 使用 Anthropic Messages 协议。Oimi API 的 Claude 兼容接口地址是 https://api.oimi.xin/v1/messages，但在 Claude Code 里通常只需要填写基础服务地址 https://api.oimi.xin，客户端会自动拼接具体路径。

Windows PowerShell：

$env:ANTHROPIC_BASE_URL="https://api.oimi.xin"
$env:ANTHROPIC_AUTH_TOKEN="你的 Oimi API 密钥"
$env:ANTHROPIC_MODEL="model-id"
claude

macOS / Linux：

export ANTHROPIC_BASE_URL="https://api.oimi.xin"
export ANTHROPIC_AUTH_TOKEN="你的 Oimi API 密钥"
export ANTHROPIC_MODEL="model-id"
claude

如果你希望小任务也固定使用同一个模型，可以同时设置：

export ANTHROPIC_SMALL_FAST_MODEL="model-id"

注意：如果工具要求填写“基础地址”，请填 https://api.oimi.xin；如果工具明确要求填写“完整接口地址”，才填写 https://api.oimi.xin/v1/messages。

OpenCode

OpenCode 可以通过自定义 OpenAI 兼容提供方接入 Oimi API。适合已经习惯在终端里使用 OpenCode 的用户。

常见配置文件位置：

  • Windows：%APPDATA%\opencode\opencode.jsonc
  • macOS / Linux：~/.config/opencode/opencode.jsonc

如果你的 OpenCode 版本提供配置目录命令或图形化设置，请优先使用当前版本展示的位置。

在配置文件中加入一个 Oimi API 提供方：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "oimi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Oimi API",
      "options": {
        "baseURL": "https://api.oimi.xin/v1",
        "apiKey": "{env:OIMI_API_KEY}"
      },
      "models": {
        "model-id": {
          "name": "model-id"
        }
      }
    }
  }
}

然后设置环境变量并启动 OpenCode。

Windows PowerShell：

$env:OIMI_API_KEY="你的 Oimi API 密钥"
opencode

macOS / Linux：

export OIMI_API_KEY="你的 Oimi API 密钥"
opencode

进入 OpenCode 后，选择 oimi 提供方和 model-id 模型。如果你的 OpenCode 版本使用 /connect 或 /models 命令，请按界面提示选择自定义提供方，并填写同样的服务地址、API 密钥和模型 ID。

Gemini

Oimi API 支持 Gemini 兼容协议，接口形态为：

https://api.oimi.xin/v1beta/models/model-id:generateContent

认证可以使用 x-goog-api-key Header，也可以使用 ?key= 查询参数。

如果你使用的 Gemini 客户端支持自定义服务地址，请按下面填写：

  • 服务地址：https://api.oimi.xin
  • API 密钥：你的 Oimi API 密钥
  • 模型 ID：从「模型」页面复制
  • 接口路径：/v1beta/models/model-id:generateContent

可以先用 curl 验证 Gemini 兼容接口是否可用。

Windows PowerShell：

$env:OIMI_API_KEY="你的 Oimi API 密钥"
curl "https://api.oimi.xin/v1beta/models/model-id:generateContent?key=$env:OIMI_API_KEY" `
  -H "Content-Type: application/json" `
  -d "{\"contents\":[{\"parts\":[{\"text\":\"用一句话介绍 Oimi API\"}]}]}"

macOS / Linux：

export OIMI_API_KEY="你的 Oimi API 密钥"
curl "https://api.oimi.xin/v1beta/models/model-id:generateContent?key=$OIMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"用一句话介绍 Oimi API"}]}]}'

部分 Gemini CLI 版本只支持 Google 官方服务地址，不提供自定义服务地址。如果你的客户端没有自定义服务地址选项，可以改用 CC-Switch 或其他支持代理 / 自定义地址的客户端。

CC-Switch

CC-Switch 适合需要在 Claude Code、Codex、OpenCode、Gemini 等工具之间切换不同服务提供方的用户。它通常通过图形界面保存服务地址、API 密钥和模型配置，再把配置应用到对应客户端。

在 CC-Switch 中新增 Oimi API 提供方时，可以按下面填写：

  • 名称：Oimi API
  • 服务地址：https://api.oimi.xin
  • OpenAI 兼容服务地址：https://api.oimi.xin/v1
  • API 密钥：你的 Oimi API 密钥
  • 模型：model-id

如果 CC-Switch 要求选择协议：

  • Claude Code：选择 Anthropic / Claude 兼容协议，基础地址填 https://api.oimi.xin
  • Codex / OpenCode：选择 OpenAI 兼容协议，地址填 https://api.oimi.xin/v1
  • Gemini：选择 Gemini 兼容协议，基础地址填 https://api.oimi.xin

如果界面要求填写完整接口地址，而不是基础地址：

  • Claude Messages：https://api.oimi.xin/v1/messages
  • OpenAI Chat Completions：https://api.oimi.xin/v1/chat/completions
  • Gemini generateContent：https://api.oimi.xin/v1beta/models/model-id:generateContent

保存后，将 Oimi API 设置为当前提供方，再打开对应客户端测试。建议先在「体验中心」确认同一个 API 密钥和模型可以正常调用，再排查客户端配置。

接入后如何验证

配置完成后，按这个顺序排查最有效：

  • 先在「体验中心」选择同一个 API 密钥和模型发起测试
  • 再用 curl 或 SDK 发起一次最小请求
  • 最后打开 Codex、Claude Code、OpenCode、Gemini 或 CC-Switch 测试
  • 如果失败，进入「用量」查看是否产生请求记录
  • 如果没有请求记录，优先检查服务地址、Header 和 API 密钥是否填错
  • 如果有请求记录，查看错误信息、模型 ID、额度和模型变体是否匹配

7. 查看用量和账单

进入「用量」页面，可以按时间、模型、API 密钥、分组、请求 ID、上游请求 ID 过滤调用记录。

用量记录会展示：

  • 消耗额度
  • RPM / TPM
  • 模型名称
  • API 密钥名称
  • 请求时间
  • 计费明细
  • 延迟与响应信息

进入「费用」页面，可以查看账户余额、充值入口和账单记录。如果请求失败并提示额度不足，请先检查账户余额，再检查对应 API 密钥的额度设置。

快速开始

创建 API 密钥，复制模型 ID，并完成第一次 Oimi API 调用。

API 接口文档

查看 Oimi API 的服务地址、认证方式和常用协议入口。