API 概览

Omniall AI 是统一的 AI API 网关。请求与响应形态对齐 OpenAI Chat Completions（以及相关媒体 API），并额外提供 Claude Messages、Gemini 原生路径与异步视频任务接口。总体原则：在多个上游供应商之上统一鉴权、路由、计费与响应结构，你只需一套 Base URL 和一把 API Key，即可调用文本、图像、视频与音频模型。

OpenAPI 规范

交互式参数说明与 Playground 由公开 OpenAPI 文档生成。可在本页所在 API Reference 页签中浏览嵌套的对话（ChatGPT / Claude / Gemini / Responses），以及图像、视频、音频、平台 API、重排序。可使用 Playground 对生产环境（https://api.omniall.ai）携带你自己的密钥试调。

Base URL

https://api.omniall.ai/v1

大多数 OpenAI 兼容客户端应将 Base URL 设为 https://api.omniall.ai/v1（包含 /v1）。官网与控制台仍使用 https://omniall.ai。下表在非 /v1 前缀（如 Gemini /v1beta）时按 API 主机根路径书写，便于对照。

认证

在控制台 API Keys 创建令牌，请求时携带：

Authorization: Bearer sk-your-key
Content-Type: application/json

Claude 风格客户端可在 /v1/messages 与模型列表路由上使用 x-api-key 配合 anthropic-version。Gemini 风格客户端可在 Gemini 兼容模型路由上使用 x-goog-api-key 或查询参数 ?key=。主路径 /v1/* 均支持 Bearer 鉴权。

能力一览

能力	方法与路径	说明
列出模型	`GET /v1/models`	当前密钥/分组可用模型
Chat Completions	`POST /v1/chat/completions`	OpenAI Chat；支持流式
Completions	`POST /v1/completions`	旧版文本补全
Responses	`POST /v1/responses`	OpenAI Responses API
Claude Messages	`POST /v1/messages`	Anthropic Messages 形态
图像	`POST /v1/images/generations`	另有 `/v1/images/edits`
Embeddings	`POST /v1/embeddings`
语音合成	`POST /v1/audio/speech`	TTS
MiniMax 音乐	`POST /v1/music_generation`	MiniMax 官方音乐生成
Suno	`POST /suno/submit/{action}`、`GET /suno/fetch/{id}`	异步音乐 / 歌词
语音转写 / 翻译	`POST /v1/audio/transcriptions`、`/v1/audio/translations`
视频（异步）	`POST /v1/videos`、`POST /v1/video/generations`	先创建任务再轮询
视频状态	`GET /v1/videos/{task_id}`、`GET /v1/video/generations/{task_id}`
文件上传	`POST /v1/files`	multipart `file` → CDN URL
Gemini	`POST /v1beta/models/{model}:{action}`	Gemini 原生路径
Realtime	`GET /v1/realtime`	WebSocket

模型接入说明见 Docs 页签下的指南。 model 请使用模型广场展示的精确模型名。

请求

Chat Completions

POST /v1/chat/completions 是文本（及多模态对话）的主入口，请求体兼容 OpenAI：

type ChatCompletionRequest = {
  model: string; // 来自模型广场，例如 "gpt-4o-mini"
  messages: Message[];
  stream?: boolean;
  temperature?: number;
  top_p?: number;
  max_tokens?: number;
  stop?: string | string[];
  tools?: Tool[];
  tool_choice?: "none" | "auto" | { type: "function"; function: { name: string } };
  response_format?: { type: "json_object" } | { type: "json_schema"; json_schema: object };
  // 以及所选模型支持的其他 OpenAI 风格字段
};

type Message = {
  role: "system" | "user" | "assistant" | "tool";
  content: string | ContentPart[];
  name?: string;
  tool_call_id?: string;
};

curl https://api.omniall.ai/v1/chat/completions \
  -H "Authorization: Bearer $OMNIALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "人生的意义是什么？" }
    ]
  }'

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",
    base_url="https://api.omniall.ai/v1",
)

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "人生的意义是什么？"}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-...",
  baseURL: "https://api.omniall.ai/v1",
});

const resp = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "人生的意义是什么？" }],
});
console.log(resp.choices[0].message.content);

流式输出

设置 stream: true。响应为 SSE（Server-Sent Events）。分片的 object 为 "chat.completion.chunk"，内容在 choices[].delta 中。可忽略 SSE 注释行；流以 data: [DONE] 结束。

curl https://api.omniall.ai/v1/chat/completions \
  -H "Authorization: Bearer $OMNIALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "stream": true,
    "messages": [{"role": "user", "content": "你好"}]
  }'

模型选择

始终传入模型广场或 GET /v1/models 中的 model ID。
可用性取决于账号分组、渠道路由与余额。
某上游模型不支持的参数通常会被忽略；支持的字段会转发到上游。

图像

curl https://api.omniall.ai/v1/images/generations \
  -H "Authorization: Bearer $OMNIALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "一间安静的工作室",
    "n": 1,
    "size": "1024x1024"
  }'

视频（异步任务）

视频接口为异步：先创建任务，再轮询至完成。常用路径：

操作	路径
创建	`POST /v1/videos` 或 `POST /v1/video/generations`
查询	`GET /v1/videos/{task_id}` 或 `GET /v1/video/generations/{task_id}`

请求体字段（prompt、seconds、image / images、metadata 等）随模型系列变化。详见 Docs 中 Kling、Doubao Seedance、Veo 等指南。

curl -X POST https://api.omniall.ai/v1/videos \
  -H "Authorization: Bearer $OMNIALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-2.5",
    "prompt": "日落时分海岸公路的航拍镜头",
    "seconds": "5"
  }'

Claude Messages 与 Gemini

Claude：POST /v1/messages，使用 Anthropic Messages JSON（model、max_tokens、messages 等）。
Gemini：POST /v1beta/models/{model_name}:{action}（如 generateContent）；若模型以 OpenAI 兼容方式开放，也可走 /v1/chat/completions。

响应

非流式 Chat Completions 对齐 OpenAI：choices 恒为数组。每项含 message（流式则为 delta）与 finish_reason。

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 4,
    "total_tokens": 14
  }
}

常见 finish_reason：stop、length、tool_calls、content_filter。上游返回用量时会出现在 usage；计费按 Omniall 额度与模型广场定价结算。视频创建接口返回任务 ID；轮询状态接口直至完成，再从任务结果读取成片 URL（或内容下载路径，若该模型提供）。

错误与限制

失败时返回 JSON 错误体（在适用情况下为 OpenAI 风格的 error.message / error.type）。常见原因：

API Key 缺失或无效
model 未知或无权使用
余额 / 额度不足
密钥或模型维度的速率限制
上游供应商错误（视路由策略重试或透传）

下一步

在 Endpoints 使用交互式 Playground 试调
快速开始配置 SDK
模型广场查看模型 ID 与定价
Docs 页签查阅图像 / 视频 / 音频模型指南

​API 概览

​OpenAPI 规范

​Base URL

​认证

​能力一览

​请求

​Chat Completions

​流式输出

​模型选择

​图像

​视频（异步任务）

​Claude Messages 与 Gemini

​响应

​错误与限制

​下一步