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

# 选择接口格式

> 根据客户端、模型能力和任务类型选择 MaxAPI 接口。

MaxAPI 同时提供 OpenAI 兼容接口和厂商原生格式。所有格式使用相同的账户体系，但路径、请求字段和响应结构可能不同。

## 快速选择

| 你的需求           | 推荐格式        | 常见路径                                        | 返回方式        |
| -------------- | ----------- | ------------------------------------------- | ----------- |
| 迁移现有 OpenAI 应用 | OpenAI 兼容格式 | `/v1/chat/completions`、`/v1/embeddings`     | 通常同步返回      |
| 生成图像或处理音频      | OpenAI 兼容格式 | `/v1/images/generations`、`/v1/audio/*`      | 取决于接口定义     |
| 使用模型的高级参数      | 厂商原生格式      | `/aistudio/*`、`/wan/*`、`/kling/*`、`/vidu/*` | 保留厂商结构      |
| 生成视频、音乐或其他耗时内容 | 创建任务与查询任务接口 | 以对应模型的接口页为准                                 | 返回任务 ID 后轮询 |

<Tip>
  如果两种格式都能满足需求，优先使用现有客户端原生支持的格式。这样可以减少请求和响应转换代码。
</Tip>

## 确认 Base URL

OpenAI SDK 的 `base_url` 通常包含 `/v1`：

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

直接发送 HTTP 请求时，请使用接口页显示的完整路径：

```text theme={null}
https://api.maxapi.ai/v1/chat/completions
```

<Warning>
  不要给厂商原生路径自动添加 `/v1`。例如，`/wan/*`、`/kling/*` 和 `/vidu/*` 应直接拼接到 `https://api.maxapi.ai`。
</Warning>

## 按顺序做出选择

<Steps>
  <Step title="确认客户端协议">
    先检查你的 SDK 或应用支持 OpenAI、Google、厂商原生格式中的哪一种。现有 OpenAI 客户端通常只需修改 Base URL、API Key 和模型 ID。
  </Step>

  <Step title="确认模型能力">
    在 MaxAPI 控制台中复制模型 ID，并确认模型是否支持文本、图像、视频、音频或音乐能力。
  </Step>

  <Step title="确认执行方式">
    同步接口会在当前响应中返回结果。异步接口会先返回任务 ID，你需要调用配套的查询接口。
  </Step>

  <Step title="核对接口结构">
    打开对应接口页，核对认证头、内容类型、必填字段和响应示例。不要在不同厂商接口之间复用未经转换的请求体。
  </Step>
</Steps>

## 不要混用请求结构

同一种能力可能有多个接口格式。例如，视频接口可能使用 `id`、`task_id` 或 `taskId` 表示任务 ID，也可能使用不同的状态值。

* 按创建接口返回的字段读取任务 ID。
* 使用同一接口族中的查询接口。
* 按查询接口定义判断成功或失败状态。
* 及时下载生成结果。资源 URL 可能过期。

<CardGroup cols={2}>
  <Card title="发送第一个请求" icon="rocket" href="/quickstart">
    使用 OpenAI 兼容格式完成聊天请求。
  </Card>

  <Card title="处理异步任务" icon="clock" href="/guides/async-tasks">
    实现任务轮询、超时和重试。
  </Card>
</CardGroup>