> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omniall.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API 概览

> Omniall AI API Reference 概览：认证、端点、请求/响应结构与模型选择。

# API 概览

Omniall AI 是统一的 AI API 网关。请求与响应形态对齐 [OpenAI Chat Completions](https://platform.openai.com/docs/api-reference/chat)（以及相关媒体 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

```text theme={null}
https://api.omniall.ai/v1
```

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

## 认证

在[控制台](https://omniall.ai/dashboard) **API Keys** 创建令牌，请求时携带：

```http theme={null}
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` 请使用[模型广场](https://omniall.ai/pricing)展示的**精确模型名**。

## 请求

### Chat Completions

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

```typescript theme={null}
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;
};
```

<CodeGroup>
  ```bash cURL theme={null}
  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": "人生的意义是什么？" }
      ]
    }'
  ```

  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  ```
</CodeGroup>

### 流式输出

设置 `stream: true`。响应为 [SSE（Server-Sent Events）](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)。分片的 `object` 为 `"chat.completion.chunk"`，内容在 `choices[].delta` 中。可忽略 SSE 注释行；流以 `data: [DONE]` 结束。

```bash theme={null}
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": "你好"}]
  }'
```

### 模型选择

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

### 图像

```bash theme={null}
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 等指南。

```bash theme={null}
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`。

```json theme={null}
{
  "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 试调
* [快速开始](/zh-CN/quickstart) 配置 SDK
* [模型广场](https://omniall.ai/pricing) 查看模型 ID 与定价
* Docs 页签查阅图像 / 视频 / 音频模型指南


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.