Omnis API 客户快速开始

确认连接信息

完整 API Key 仅在创建时展示一次。请保存到密码管理器或受保护的环境变量，不要写入源码、提交到 Git 或发送到聊天和工单。

私有部署或测试环境必须以控制台“快速开始”展示的地址为准。API Endpoint 不带 /v1；OpenAI Base URL 带 /v1。

export OMNIS_API_KEY='粘贴刚创建的完整密钥'
export OMNIS_BASE_URL='https://api.omnisai.cn/v1'

查询授权模型

模型 ID 是 Omnis 对客户暴露的公开标识，不能根据其他平台或上游 Provider 文档猜测。平台目录包含十个 omnis-* Responses 模型和三个 omnis-image-* Images generation 模型；实际可用范围由当前租户授权、供给分配和活动路由共同决定。调用 GET /v1/models?protocol=openai_responses 或 ?protocol=openai_images 查询当前 API Key 的真实可用模型。

curl "$OMNIS_BASE_URL/models?protocol=openai_responses" \
  -H "Authorization: Bearer $OMNIS_API_KEY"

发起首次调用

先用非流式、无工具调用的最小 POST /v1/responses 请求验证连接，再逐步启用高级能力。

curl "$OMNIS_BASE_URL/responses" \
  -H "Authorization: Bearer $OMNIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'OMNIS_REQUEST'
{
  "model": "从模型列表复制的ID",
  "input": "请只回复：连接成功",
  "stream": false
}
OMNIS_REQUEST

Python 与 Node.js SDK

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OMNIS_API_KEY"],
    base_url=os.environ["OMNIS_BASE_URL"],
)
response = client.responses.create(
    model="从模型列表复制的ID",
    input="你好",
)
print(response.output_text)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OMNIS_API_KEY,
  baseURL: process.env.OMNIS_BASE_URL
});
const response = await client.responses.create({
  model: "从模型列表复制的ID",
  input: "你好"
});
console.log(response.output_text);

第三方客户端与一键部署

OpenAI-compatible 客户端

API Key 填控制台创建的密钥，Base URL 填带 /v1 的 OpenAI Base URL，Model 填 GET /v1/models?protocol=openai_responses 返回的 ID。客户端必须支持 Responses；如果它会自动追加 /v1，则改填 Gateway 根地址，避免出现 /v1/v1。

共同步骤

部署前请确认设备能访问控制台、Gateway 和 Omnis 客户端镜像，终端用户无需访问 GitHub。macOS/Linux 需要 curl 或 wget；Windows 原生部署支持可双击的 CMD 文件和可检查的 PowerShell 脚本，两者都支持 Windows 10/11 x64/ARM64、Windows PowerShell 5.1 与 PowerShell 7，无需预装 Node.js 或 npm。WSL 用户应在 WSL 内选择 macOS/Linux 脚本，不要混用两套配置。

1. 登录控制台，进入左侧“API Key”。
2. 点击“一键部署 Codex”或“一键部署 OpenCode”，确认默认模型和已验收版本。
3. 选择 macOS/Linux、Windows CMD 或 Windows PowerShell。不熟悉终端时优先下载可双击的 .cmd；也可以下载 .sh 或 .ps1。文件卡片右侧可复制运行命令。
4. 在自己的可信设备执行。脚本中的授权只有 10 分钟有效且只能使用一次；失败或过期后回控制台重新生成。

cd ~/Downloads
chmod 700 ./omnis-codex-setup.sh
./omnis-codex-setup.sh

# OpenCode
chmod 700 ./omnis-opencode-setup.sh
./omnis-opencode-setup.sh

powershell.exe -NoProfile -ExecutionPolicy Bypass `
  -File "$HOME\Downloads\omnis-codex-setup.ps1"

# OpenCode
powershell.exe -NoProfile -ExecutionPolicy Bypass `
  -File "$HOME\Downloads\omnis-opencode-setup.ps1"

"%USERPROFILE%\Downloads\omnis-codex-setup.cmd" --no-pause

rem OpenCode
"%USERPROFILE%\Downloads\omnis-opencode-setup.cmd" --no-pause

omnis-codex-setup.cmd

rem 或
omnis-opencode-setup.cmd

Windows 请使用日常登录的普通用户，不需要管理员权限。CMD 文件是同一份 PowerShell 部署逻辑的双击包装；双击后窗口会保留结果。它使用进程级 -ExecutionPolicy Bypass 运行当前下载文件，但不修改机器的持久执行策略，也无法绕过 Group Policy、Windows Defender、WDAC 或 AppLocker。浏览器若保存到 OneDrive 或自定义目录，请替换命令中的实际路径。脚本会先完成系统、PowerShell 和架构预检，再兑换一次性授权、创建专用 API Key、下载并校验固定客户端版本、写入仅当前用户可读的隔离配置和启动器，最后逐个确认模型授权。安装验证不发送推理 Prompt，不消耗推理额度；任一步失败会恢复原文件。不要转发下载脚本。

Codex CLI

Omnis 使用独立 omnis Profile，不覆盖默认 config.toml。默认目录 ~/.codex/omnis 中，omnis.config.toml 保存 Provider，omnis.models.json 保存完整模型选择器目录；POSIX 使用 omnis.env，原生 Windows 使用 omnis.key 保存专用密钥。脚本成功后会自动启动；以后请使用脚本打印的 omnis-codex 启动器，不要用全局 codex 判断部署结果。进入 Codex 后输入 /model，应看到当前 API Key 已授权并通过 Codex 兼容验收的全部文本模型。默认模型只是首次选中项，图片模型不会进入 Codex 目录。

OpenCode

OpenCode 使用独立 omnis Provider，不覆盖已有 Provider。默认目录 ~/.config/opencode/omnis 中，omnis.json 保存完整模型目录，omnis.key 保存专用密钥。以后请使用脚本打印的 omnis-opencode 启动器；直接运行全局 opencode 可能仍显示原有 Provider。使用 omnis-opencode models omnis 应列出全部 omnis/<公开模型ID>，并可在模型选择器中切换；不要用裸命令 opencode models omnis 判断隔离部署结果。默认模型不是唯一模型，图片模型不会进入 Responses 编程客户端目录。

失败时怎么处理

使用图片模型生成图片

omnis-image-1、omnis-image-1.5 和 omnis-image-2 都使用 POST /v1/images/generations，不能发给 Responses 接口。三者使用同一请求契约，下面以 omnis-image-2 为例。先查询 GET /v1/models?protocol=openai_images；只有模型出现在当前 API Key 的返回结果中，才表示租户已获得对应图片路由和授权。

curl "$OMNIS_BASE_URL/models?protocol=openai_images" \
  -H "Authorization: Bearer $OMNIS_API_KEY"

选择图片模型

三个 ID 是独立计费和路由标识，不会自动降级或互相替换。若指定模型暂时没有号池容量，请保留原幂等键并退避重试，不要静默改用另一代。

当前能力边界

自定义宽高必须同时是 16 的倍数，单边不超过 3840，总像素在 655,360 到 8,294,400 之间，宽高比在 1:3 到 3:1 之间。最终以模型返回的 image_capabilities 为准。

Console 的“参考单张”价格来自管理员已双人审批并生效的价格版本，并同时标明参考输出尺寸、质量档位和估算 Token 口径。AI 生图价格存在波动，页面金额仅供参考，最终费用以每次请求实际返回并结算的 input/output usage 为准。

完整 curl 请求

export OMNIS_IMAGE_IDEMPOTENCY_KEY="image-$(date +%s)-$$"

curl -sS -D omnis-image.headers \
  "$OMNIS_BASE_URL/images/generations" \
  -H "Authorization: Bearer $OMNIS_API_KEY" \
  -H "Idempotency-Key: $OMNIS_IMAGE_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omnis-image-2",
    "prompt": "纯白背景上的蓝色几何产品模型，柔和棚拍光线",
    "size": "1024x1024",
    "quality": "high",
    "output_format": "png",
    "background": "opaque",
    "n": 1
  }' \
  -o omnis-image.json

成功响应把图片放在 data[0].b64_json，不是长期 URL。服务端不会保存图片正文，请立即落盘并保留原始响应：

jq -r '.data[0].b64_json' omnis-image.json > omnis-image.b64
base64 --decode omnis-image.b64 > omnis-image.png 2>/dev/null || \
  base64 -D omnis-image.b64 > omnis-image.png
file omnis-image.png

Python 与 Node.js 落盘

import base64, json, os, uuid
from pathlib import Path
from urllib.request import Request, urlopen

data = json.dumps({
  "model": "omnis-image-2",
  "prompt": "蓝色几何产品模型",
  "size": "1024x1024",
  "output_format": "png",
  "n": 1
}).encode()
req = Request(
  os.environ["OMNIS_BASE_URL"] + "/images/generations",
  data=data,
  headers={
    "Authorization": "Bearer " + os.environ["OMNIS_API_KEY"],
    "Content-Type": "application/json",
    "Idempotency-Key": "image-" + str(uuid.uuid4()),
  }, method="POST")
with urlopen(req, timeout=180) as res:
  body = json.load(res)
Path("omnis-image.png").write_bytes(
  base64.b64decode(body["data"][0]["b64_json"], validate=True))

import { randomUUID } from "node:crypto";
import { writeFile } from "node:fs/promises";

const res = await fetch(
  process.env.OMNIS_BASE_URL + "/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OMNIS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `image-${randomUUID()}`
  },
  body: JSON.stringify({
    model: "omnis-image-2",
    prompt: "蓝色几何产品模型",
    size: "1024x1024",
    output_format: "png",
    n: 1
  })
});
const body = await res.json();
if (!res.ok) throw new Error(JSON.stringify(body));
await writeFile("omnis-image.png",
  Buffer.from(body.data[0].b64_json, "base64"));

计费与重试

保存响应头中的 x-request-id、x-billing-status 和 x-provider-acceptance。settled 表示已结算，billing_pending 表示账务仍在收敛，不能理解为免费。网络中断时，同一逻辑操作只能复用完全相同的请求正文和原 Idempotency-Key；换 Key 重发可能产生第二次调用和费用。由于服务端不保存图片正文，已处理的同 Key 请求会返回 409，不会重放原图。

常见问题