OmniModel 开发者使用指南

面向开发者的实操手册。
目标：从零开始，在 15 分钟内完成首次 API 调用；并能熟练管理 Token、查日志、排故障、做集成。

---

一、什么是 OmniModel

OmniModel 是一款 AI 模型聚合与分发网关。一句话讲清楚它对开发者的意义：写一次 OpenAI 兼容代码，就能调用 40+ 家上游模型（OpenAI、Claude、Gemini、Azure、AWS Bedrock、DeepSeek、Qwen 等），账单合并、日志统一、配额可控。

它不是 SDK，也不是 IDE 插件，它是一个 HTTP API 网关，部署在 https://www.omnimodel.pro/ 或你自己的服务器上。你向它发请求，它向上游发请求，再把响应翻译回 OpenAI 兼容格式发给你。整个过程中你不用知道 Claude 的 Messages 协议、Gemini 的字段差异、Bedrock 的签名方式。

在落地页底部还能直接看到当前支持的模型清单与基础定价：

所有倍率都明牌列出——这意味着你在写代码之前就能预算清楚每千 Token 的成本。

---

二、注册与登录

打开 https://www.omnimodel.pro/，点击右上角"注册"。注册方式有四种：

1. 邮箱 + 密码（最快）
2. GitHub OAuth（一键登录）
3. Discord / LinuxDO / 自定义 OIDC
4. Passkey / WebAuthn（无密码，最安全）

注册完成后，强烈建议立刻在「个人设置 → 安全」启用 2FA，并下载备份码。这一步只花一分钟，但可以避免日后所有"账号被盗"类问题。

---

三、控制台速览

登录后会进入数据看板，左侧导航分为工作台、财务/渠道、管理三组：

数据看板上方是用量摘要（本月调用次数、消耗额度、可用余额），下方是按时间维度的趋势图。第一次进来，先确认你的初始配额——注册即赠送少量免费额度供试用。

控制台首页则给出更聚合的视图：

---

四、创建你的第一个 API Token

进入「工作台 → 令牌管理」：

点击「添加新的令牌」，关键字段：

• 名称：方便识别，例如 local-dev / prod-server-1；
• 额度：单 Token 配额上限，生产 Token 强烈建议设硬上限；
• 过期时间：建议生产环境设 90 天；
• 可调用模型：可勾选只允许特定模型，权限最小化；
• IP 白名单：服务器侧使用强烈建议加上。

创建完成后点击"复制密钥"获得 sk-... 形式的 Token。全文只显示一次，请立刻保存到密码管理器或环境变量。

---

五、第一次 API 调用

5.1 curl

curl https://www.omnimodel.pro/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-omnimodel-xxxxxxxx" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

5.2 Python（官方 OpenAI SDK）

from openai import OpenAI

client = OpenAI(
    base_url="https://www.omnimodel.pro/v1",
    api_key="sk-omnimodel-xxxxxxxx",
)

resp = client.chat.completions.create(
    model="claude-3-5-sonnet",      # 改这一行就切换模型
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

5.3 Node.js

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://www.omnimodel.pro/v1',
  apiKey: process.env.OMNIMODEL_KEY,
});

const resp = await client.chat.completions.create({
  model: 'gemini-2.0-pro',
  messages: [{ role: 'user', content: 'Hi' }],
});

核心要点：所有上游模型都遵循同一份 OpenAI Chat Completions 规范，切换模型只需改 model 字段，无需重写任何代码。流式响应把 stream: true 加进去即可，OmniModel 会把 Claude / Gemini 的私有协议流式分片自动翻译成 OpenAI SSE 格式。

---

六、充值与计费

「钱包管理」里可选：

• Stripe / Waffo：国际信用卡（含外卡友好通道）；
• USDT (ERC20 / TRC20)：加密货币，无 KYC；
• Epay / Creem：聚合支付通道。

USDT 通常 1–3 个区块到账。充值进入账户总额度，所有 Token 共享，除非你为单 Token 设了独立配额。

计费分两种：按 Token 计费（input / output 分别计价，部分模型还区分缓存命中价）和按次计费（绘图、TTS、视频等）。

---

七、Playground：浏览器内实时调试

如果只是想快速测试模型效果，不必写代码，直接打开顶栏「Playground」：

• 左侧：选择模型、调整 temperature / top_p / max_tokens；
• 中间：多轮对话；
• 右侧：完整请求 / 响应 JSON，方便复制到代码里。

Playground 同样会扣 Token 配额，调试时挑便宜的小模型（gpt-4o-mini、claude-3-haiku、deepseek-chat）即可。

---

八、日志查询与故障排查

「使用日志」按时间倒序显示每一次调用的详情：Token、模型、上游渠道、input/output token 数、单次扣费、缓存命中、HTTP 状态码、上游错误信息、首字节延迟和总耗时。

排故障三步法：

1. 400 / 401：Token 错误、过期或权限不足；
2. 402 / quota exceeded：账户或 Token 配额耗尽；
3. 429 / 5xx：上游限流或临时故障，OmniModel 已对多 Key 渠道自动 failover，可以稍后重试。

---

九、（高级）多 Channel 与多 Key 管理

如果你是管理员或卖家，「渠道管理」是核心页面。每一个"渠道"对应一组上游 Key（同一供应商可挂多个 Key 做轮询）：

• 类型：上游供应商；
• Base URL：默认值即官方端点；
• Key(s)：可填多个，逗号或换行分隔，自动轮询 + failover；
• 模型映射：把上游模型名映射到对外暴露的模型名；
• 倍率：在全局倍率之上再做单渠道倍率调整。

卖家模式：在「我的渠道」挂上你持有的 ChatGPT Pro / Claude Pro / Gemini Advanced Key，平台按调用量结算给你。在「渠道收益」页查看累计收入、近 7 日趋势、按模型/Token 明细，支持 JSON 导出。

---

十、个人设置与账户安全

在「个人设置」可以：

• 修改昵称、邮箱、密码；
• 开关 2FA（基于 TOTP）；
• 注册 / 管理 Passkey（无密码登录）；
• 绑定 / 解绑 OAuth（GitHub、Discord、Telegram 等）；
• 查看 / 复制邀请链接（如启用多级分润）；
• 设置首选语言（6 国语言）。

安全建议清单：永远不要把 Token 提交到 Git、生产 Token 设 IP + 模型白名单、个人账户开 2FA、定期轮换 Token、管理员定期审计日志。

---

十一、常见集成

OmniModel 100% OpenAI 兼容，主流框架都开箱可用：

• LangChain / LlamaIndex：OPENAI_API_BASE 指到 https://www.omnimodel.pro/v1；
• Dify / FastGPT / RAGFlow：选"OpenAI 兼容"，填 base_url 和 key；
• Cursor / Continue.dev / Cline：设置里填自定义 OpenAI base URL；
• AI Agent 框架（CrewAI、AutoGen、AG2、Letta…）：使用 OpenAI SDK，配置同上。

---

十一之一、高级用法

OmniModel 不只是 chat completions。OpenAI SDK 中的几个高阶能力都已支持：

• Function Calling / Tools：在请求中传 tools，OmniModel 把 Claude 的 tool_use、Gemini 的 functionCall 都翻译为 OpenAI 标准的 tool_calls 返回结构；
• Vision / 多模态：在 content 里传 image_url 数组即可，Claude / GPT-4o / Gemini 自动适配；
• Embeddings：调用 /v1/embeddings，传 text-embedding-3-small 等模型；
• 绘图 / 视频 / TTS：参考 /v1/images/generations、/v1/audio/speech，与 OpenAI 完全一致；
• JSON 模式：传 response_format={"type":"json_object"}，OmniModel 自动注入 fallback system prompt 保证可靠 JSON。

resp = client.chat.completions.create(
    model="claude-3-5-sonnet",
    messages=[{"role": "user", "content": "北京天气怎么样？"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
)

---

十一之二、成本优化的几个实战技巧

1. 小模型先行：90% 的开发联调用 gpt-4o-mini / claude-3-haiku 就够，只在真正需要时切旗舰；
2. 缓存命中价：对长 system prompt 应用，启用 prompt caching，通常省 50–90% 输入成本；
3. 流式 + max_tokens 双管齐下：体验更快 + 防止"啰嗦"成本爆炸；
4. Channel 多供应商比价：同一模型不同上游可能差 30%，在「渠道管理」挂多个 + 配合倍率与优先级；
5. 限流双保险：账号级 + Token 级配额一起设，防止 bug 引发死循环烧光预算。

---

十一之三、团队与多租户

OmniModel 天生多用户。中小团队配置：

• 管理员创建用户分组（如 team-internal），配置可见模型与价格倍率；
• 邀请同事注册并加入分组；
• 每位成员各自创建 Token，互不干扰；
• 管理员在「使用日志」里按用户筛选，做内部成本分摊。

需要"AI 中台"，则采用私有部署，把 OmniModel 作为公司唯一的 LLM 出口，所有业务线统一接入。

---

十二、错误码速查 + 找人帮忙

状态码	含义	常见原因
400	请求格式错误	JSON / 必填字段错误
401	鉴权失败	Token 错或已删
402	配额不足	余额 0 / Token 配额耗尽
403	无权限	模型 / IP 未授权
404	模型不存在	model 拼错
429	限流	RPM / TPM 上限或上游限流
5xx	上游故障	自动重试或换渠道

「工作台 → 我的工单」可直接开工单，支持文字 + 图片附件（最多 9 张，单张 ≤ 2MB）。新回复会以红色「未读」Tag 高亮，所有支持流程都在平台内闭环。

---

十三、下一步

1. 在 Playground 试 3 个最常用模型，对比效果与单价；
2. 把生产代码 base_url 切到 OmniModel，加日志比对响应；
3. 团队 > 1 人，创建多用户、按用户分 Token 和配额；
4. 数据合规要求高，考虑私有化部署版本——开工单联系我们。

祝顺利构建 ✨