> ## 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 完成第一个聊天请求。

本指南使用 OpenAI 兼容的聊天补全接口。开始前，你需要：

* MaxAPI 账户和 API Key。
* 控制台中可用的模型 ID。
* `curl`、Python 3.8+ 或 Node.js 18+。

<Steps>
  <Step title="创建 API Key">
    登录 MaxAPI 控制台并创建 API Key，然后在当前终端中设置环境变量：

    ```bash theme={null}
    export MAXAPI_API_KEY="YOUR_API_KEY"
    ```

    <Warning>
      API Key 只会完整显示有限次数。请立即保存，并且不要在浏览器代码或公开仓库中暴露它。
    </Warning>
  </Step>

  <Step title="发送请求">
    将 `YOUR_MODEL_ID` 替换为控制台中显示的模型 ID。Python 和 Node.js 示例需要先安装 `openai` 包。

    <CodeGroup>
      ```bash Python theme={null}
      python -m pip install openai
      ```

      ```bash Node.js theme={null}
      npm install openai
      ```
    </CodeGroup>

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.maxapi.ai/v1/chat/completions \
        -H "Authorization: Bearer $MAXAPI_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "model": "YOUR_MODEL_ID",
          "messages": [
            {"role": "user", "content": "用一句话介绍 MaxAPI"}
          ]
        }'
      ```

      ```python Python theme={null}
      import os
      from openai import OpenAI

      client = OpenAI(
          api_key=os.environ["MAXAPI_API_KEY"],
          base_url="https://api.maxapi.ai/v1",
      )

      response = client.chat.completions.create(
          model="YOUR_MODEL_ID",
          messages=[
              {"role": "user", "content": "用一句话介绍 MaxAPI"}
          ],
      )

      print(response.choices[0].message.content)
      ```

      ```javascript Node.js theme={null}
      import OpenAI from "openai";

      const client = new OpenAI({
        apiKey: process.env.MAXAPI_API_KEY,
        baseURL: "https://api.maxapi.ai/v1",
      });

      const response = await client.chat.completions.create({
        model: "YOUR_MODEL_ID",
        messages: [
          { role: "user", content: "用一句话介绍 MaxAPI" },
        ],
      });

      console.log(response.choices[0].message.content);
      ```
    </CodeGroup>
  </Step>

  <Step title="读取响应">
    成功响应中的文本位于 `choices[0].message.content`。

    ```json theme={null}
    {
      "id": "chatcmpl-abc123",
      "object": "chat.completion",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "MaxAPI 让你通过统一接口调用多种 AI 模型。"
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 12,
        "completion_tokens": 18,
        "total_tokens": 30
      }
    }
    ```
  </Step>
</Steps>

## 常见问题

| 现象       | 检查项                                                       |
| -------- | --------------------------------------------------------- |
| 返回 `401` | 确认 `MAXAPI_API_KEY` 已设置，并且请求头包含 `Bearer` 前缀               |
| 返回 `404` | SDK 的 Base URL 使用 `https://api.maxapi.ai/v1`；直接请求使用完整接口路径 |
| 提示模型不存在  | 从控制台重新复制模型 ID，不要使用展示名称代替 ID                               |
| 请求长时间未返回 | 确认该模型是否使用异步任务接口                                           |

## 下一步

<CardGroup cols={2}>
  <Card title="选择接口格式" icon="shuffle" href="/guides/choose-api">
    判断应该使用 OpenAI 兼容格式还是厂商原生格式。
  </Card>

  <Card title="配置身份认证" icon="key" href="/guides/authentication">
    安全地管理和传递 API Key。
  </Card>

  <Card title="处理异步任务" icon="clock" href="/guides/async-tasks">
    创建并轮询视频、图像或音乐任务。
  </Card>
</CardGroup>