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

# API 概览

> 模型 API 调用的 Base URL、鉴权、请求头和响应约定。

YouRouter 通过一个统一网关暴露模型 API。大多数集成场景都应从 OpenAI 兼容的 Chat Completions 端点开始。

## Base URL

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

OpenAI 兼容接口和上游提供商原生模型接口都使用这个 base URL。视频任务和 Custom Search 使用独立路径，见下表。

## 端点家族

| 家族            | Base path                                  | 用途                                                                            |
| ------------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
| 模型 API        | `https://api.yourouter.ai/v1`              | Chat Completions、Embeddings、Anthropic Messages 和 Google `generateContent` 路径。 |
| 视频任务          | `https://api.yourouter.ai/api/v3`          | Ark 文生视频、图生视频任务创建和轮询。                                                         |
| Custom Search | `https://api.yourouter.ai/customsearch/v1` | 兼容 Google Programmable Search 的网页搜索。                                          |

## 鉴权

请把 YouRouter API Key 作为 Bearer Token 发送：

```bash theme={null}
Authorization: Bearer <YOUROUTER_API_KEY>
```

对于 JSON 请求，还需要发送：

```bash theme={null}
Content-Type: application/json
```

<Warning>
  API Key 只能用于服务端代码、后端服务、CI 任务或可信的内部工具。不要把 API Key 放在浏览器端代码或移动客户端中。
</Warning>

## 第一条 API 请求

```bash theme={null}
curl https://api.yourouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $YOUROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": "Reply with exactly: connected"
      }
    ]
  }'
```

生成结果通常位于：

```text theme={null}
choices[0].message.content
```

## 核心概念

| 概念          | 使用方式                                                                   |
| ----------- | ---------------------------------------------------------------------- |
| 模型选择        | 在请求体中设置 `model` 字段。                                                    |
| 多模态输入       | 在 `messages[].content` 中发送文本和图片内容块，或使用上游提供商原生多模态端点。                    |
| 自动路由        | 省略 `vendor` 请求头，或发送 `vendor: auto`。                                    |
| 固定上游        | 发送 `vendor: openai`、`vendor: anthropic`、`vendor: google` 等 `vendor` 值。 |
| 流式输出        | 设置 `stream: true`，按 SSE 增量返回内容。                                        |
| 上游提供商原生 API | Anthropic 使用 `/messages`；Gemini 使用 `generateContent` 路径。               |

## 主要端点

| 端点                                                  | 用途                                    |
| --------------------------------------------------- | ------------------------------------- |
| `POST /chat/completions`                            | OpenAI 兼容的文本和图片输入调用。适合大多数集成。          |
| `POST /embeddings`                                  | 生成文本向量。                               |
| `POST /messages`                                    | Anthropic Messages 兼容调用。              |
| `POST /projects/.../models/{model}:generateContent` | Google Gemini `generateContent` 兼容调用。 |
| `POST /api/v3/contents/generations/tasks`           | 任务式视频生成调用。                            |

## 状态码

| 状态码   | 含义                |
| ----- | ----------------- |
| `200` | 请求成功。             |
| `400` | 请求体、模型或参数格式无效。    |
| `401` | API Key 缺失或无效。    |
| `429` | 命中了上游提供商的限流或并发限制。 |
| `500` | 网关或上游提供商返回内部错误。   |

核心请求格式请参考 [Create Chat Completion](/zh/api-reference/chat/create)，图片和视频示例请参考 [多模态](/zh/guides/multimodal)。