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

# 快速开始

> 准备密钥、选择协议，并发送第一次 API 请求。

## 1. 准备密钥和模型

打开 [ViVi-API 控制台](https://api.viviai.cc/dashboard)，准备以下信息：

* 一个有效的 ViVi-API API Key。
* 与所选接口协议匹配、且账号有权限使用的模型 ID。
* 足够的可用额度。

> [!NOTE]
>
> 下文使用 `YOUR_OPENAI_MODEL` 作为占位符，不能直接发送。请替换为控制台中的完整模型 ID。其他两套协议分别使用 `YOUR_GEMINI_MODEL` 和 `YOUR_ANTHROPIC_MODEL`。

## 2. 选择接口协议

| 协议 | 请求路径 | 鉴权请求头 |
| - | - | - |
| [OpenAI Chat](https://docs.viviai.cc/openai-chat.md) | `/v1/chat/completions` | `Authorization: Bearer API_KEY` |
| [Gemini](https://docs.viviai.cc/gemini.md) | `/v1beta/models/MODEL:generateContent` | `x-goog-api-key: API_KEY` |
| [Anthropic](https://docs.viviai.cc/anthropic.md) | `/v1/messages` | `x-api-key: API_KEY` |

所有地址均使用 `https://api.viviai.cc` 作为主机。Anthropic 示例还需发送 `anthropic-version` 请求头。

## 3. 设置环境变量

> [tab] macOS / Linux / Bash
>
> ```bash theme={null}
> export VIVI_API_KEY="替换为你的 API Key"
> export VIVI_MODEL="YOUR_OPENAI_MODEL"
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $env:VIVI_API_KEY = "替换为你的 API Key"
> $env:VIVI_MODEL = "YOUR_OPENAI_MODEL"
> ```

## 4. 发送第一次请求

以下示例使用 OpenAI Chat 协议。cURL 示例使用 Bash 语法；Windows 可使用 Git Bash / WSL，或使用下面的 Python 示例。

```bash cURL theme={null}
curl --fail-with-body https://api.viviai.cc/v1/chat/completions \
  -H "Authorization: Bearer $VIVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$VIVI_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"你好，请用一句话介绍自己。\"}]}"
```

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://api.viviai.cc/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['VIVI_API_KEY']}"},
    json={
        "model": os.environ["VIVI_MODEL"],
        "messages": [{"role": "user", "content": "你好，请用一句话介绍自己。"}],
    },
    timeout=120,
)
response.raise_for_status()
data = response.json()
print(data["choices"][0]["message"].get("content", ""))
```

运行 Python 示例前，执行 `python -m pip install requests`。收到成功响应后，OpenAI Chat 的文本结果通常位于 `choices[0].message.content`。

## 常见问题

| 现象 | 排查方向 |
| - | - |
| 400 / 参数错误 | 检查 JSON、必填参数和模型支持的字段。 |
| 401 / 鉴权失败 | 检查密钥是否有效，以及请求头是否符合所选协议。 |
| 403 / 无权限 | 检查账号、令牌和模型的访问权限。 |
| 404 / 路径或模型不存在 | 检查路径、模型 ID，避免拼接出 `/v1/v1`。 |
| 429 / 请求受限 | 查看错误正文和额度，降低并发；按服务提示退避重试。 |
| 5xx / 服务异常 | 保留请求时间与请求 ID；根据错误类型决定是否重试。 |

具体原因以接口返回的错误正文为准。对超时请求重试前，应考虑原请求可能已经执行，避免重复调用和计费。

## 下一步

> [card] [OpenAI Chat](https://docs.viviai.cc/openai-chat.md)
>
> SDK 接入、多轮对话与流式输出。

> [card] [Gemini](https://docs.viviai.cc/gemini.md)
>
> contents、parts 和 SSE 流式调用。

> [card] [Anthropic](https://docs.viviai.cc/anthropic.md)
>
> Messages、system 与输出长度控制。


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