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

# 快速开始

> 创建 XRouter API Key，并用 OpenAI 兼容接口完成第一次调用。

本页用于验证 XRouter API Key、服务地址和模型名是否可用。无论你后续接入应用代码、Claude Code、Codex CLI 还是 CC-Switch，都建议先跑通一次最小请求。

## 前置条件

* 已注册并登录 XRouter 控制台：`https://api.xrouter.dev`。
* 账户可正常访问模型页或控制台首页。
* 本机已安装 `curl`；如果要运行 SDK 示例，还需要 Python 或 Node.js。

## 第一步：确认服务地址

控制台会展示当前可用的 API 服务地址。公共站默认是：

```text theme={null}
https://api.xrouter.dev
```

<Note>
  待补图片：控制台 API Info 面板，标出服务地址和复制按钮。截图中需要隐藏账号、余额和真实请求信息。
</Note>

如果你的控制台显示了不同的 `server_address`，后续示例里的 `https://api.xrouter.dev` 都应替换成控制台显示的地址。

## 第二步：创建 API Key

进入控制台的 API Keys 页面，创建一把用于测试的 Key。创建时建议：

| 字段    | 建议                             |
| ----- | ------------------------------ |
| 名称    | 使用可识别的名称，例如 `local-quickstart` |
| 额度    | 测试 Key 可以设置较小额度，或按你的账户策略保持无限额度 |
| 过期时间  | 本地测试可先不设置；生产环境建议按项目周期设置        |
| 模型限制  | 第一次验证可不限制，跑通后再按项目需要收敛          |
| IP 限制 | 不确定出口 IP 时先留空；生产环境再配置允许列表      |

<Note>
  待补图片：创建 API Key 表单。截图必须使用假密钥，并隐藏账号、余额和任何真实业务名称。
</Note>

<Warning>
  API Key 属于敏感凭据。不要把真实 Key 提交到代码仓库、Issue、截图或聊天记录中。
</Warning>

## 配置环境变量

```bash Terminal theme={null}
export XROUTER_BASE_URL="https://api.xrouter.dev"
export XROUTER_API_KEY="sk-your-api-key"
```

<Note>
  复制命令时把 `sk-your-api-key` 替换成控制台生成的真实 API Key。如果你的控制台展示了不同服务地址，也请同步替换 `XROUTER_BASE_URL`。
</Note>

## 第三步：验证 API Key

先请求模型列表，确认密钥和地址可用：

```bash Terminal theme={null}
curl "$XROUTER_BASE_URL/v1/models" \
  -H "Authorization: Bearer $XROUTER_API_KEY"
```

如果返回模型列表，说明 API Key 可以被 XRouter 识别。接着从控制台模型页复制一个可用模型 ID，用它发起一次 Chat Completions 请求。

<Note>
  待补图片：控制台模型页中复制模型 ID 的位置。第一版文档不维护完整模型清单，实际可用模型以控制台为准。
</Note>

## 第四步：发起第一次请求

<CodeGroup>
  ```bash cURL theme={null}
  curl "$XROUTER_BASE_URL/v1/chat/completions" \
    -H "Authorization: Bearer $XROUTER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "your-model-id",
      "messages": [
        {
          "role": "user",
          "content": "用一句话介绍 XRouter。"
        }
      ]
    }'
  ```

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

  client = OpenAI(
      base_url="https://api.xrouter.dev/v1",
      api_key="sk-your-api-key",
  )

  completion = client.chat.completions.create(
      model="your-model-id",
      messages=[
          {"role": "user", "content": "用一句话介绍 XRouter。"}
      ],
  )

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

  ```typescript TypeScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "https://api.xrouter.dev/v1",
    apiKey: process.env.XROUTER_API_KEY,
  });

  const completion = await client.chat.completions.create({
    model: "your-model-id",
    messages: [
      { role: "user", content: "用一句话介绍 XRouter。" },
    ],
  });

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

<Check>
  请求成功后，你可以继续配置 OpenAI SDK、Claude Code、Codex CLI 或 CC-Switch。模型名建议从控制台模型页复制，避免拼写差异。
</Check>

## 下一步

<Columns cols={2}>
  <Card title="选择接入方式" icon="list-checks" href="/guides/choose-integration">
    不确定该用哪种接口或工具时，从这里开始。
  </Card>

  <Card title="OpenAI SDK" icon="code" href="/integrations/openai-sdk">
    在 Python、TypeScript 或其他 OpenAI SDK 中接入 XRouter。
  </Card>

  <Card title="Claude Code" icon="bot" href="/integrations/claude-code">
    配置 Claude Code 使用 XRouter 的 Anthropic Messages 入口。
  </Card>

  <Card title="Codex CLI" icon="terminal" href="/integrations/codex-cli">
    配置 Codex CLI 使用 XRouter 的 Responses API 入口。
  </Card>
</Columns>

## 常见问题

<AccordionGroup>
  <Accordion title="401 或 token invalid">
    检查 API Key 是否包含完整 `sk-` 前缀，确认请求头格式是 `Authorization: Bearer sk-...`。如果你复制的是隐藏后的密钥，请重新在控制台查看或新建密钥。
  </Accordion>

  <Accordion title="模型不存在或无权限">
    先调用 `/v1/models` 查看当前密钥可用模型，再把工具中的模型名改成列表中存在的值。不同分组、Key 限制或账户状态可能影响可见模型。
  </Accordion>

  <Accordion title="本地工具显示连接失败">
    先用本页的 cURL 验证网络和密钥。如果 cURL 成功，再检查工具是否把 base URL 写成了 `https://api.xrouter.dev/v1` 或 `https://api.xrouter.dev` 对应的正确形式。
  </Accordion>
</AccordionGroup>