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

# API 参考概览

> 了解智牛API 的认证方式、基础地址、请求约定与常见错误。

## 调用方式

智牛API 采用 OpenAI 兼容的调用风格。对接时，你可以继续沿用熟悉的请求结构、SDK 用法和 `chat.completions.create(...)` 调用方式。

## 认证方式

所有请求都使用 Bearer Token 鉴权。

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Note>
  如果缺少 `Authorization` 请求头、Token 无效，或格式不正确，请求通常会返回认证相关错误。
</Note>

## Base URL

智牛API 的基础地址固定为：

```text theme={null}
https://niuapi.vip/v1
```

这意味着：

* SDK 初始化时，Base URL 应设置为 `https://niuapi.vip/v1`
* 直接请求文本对话接口时，完整路径为 `https://niuapi.vip/v1/chat/completions`
* 不要遗漏 `/v1`，也不要把重复路径拼进 Base URL

## 通用请求约定

使用智牛API 时，可以先记住这几个约定：

* 请求体使用 JSON
* 文本对话请求通常至少需要 `model` 和 `messages`
* `messages` 按数组顺序表示上下文
* 返回结果通常会包含 `id`、`object`、`created`、`model`、`choices`、`usage` 等常见字段

## 通用响应约定

一次标准的非流式成功响应，通常会有这些特点：

* `choices[0].message.content` 中包含模型输出内容
* `finish_reason` 表示本次生成结束原因
* `usage` 提供输入、输出和总 token 用量信息

如果你使用流式返回，响应会改为按块推送，客户端需要逐段消费返回内容。

## 常见状态码与错误类型

<AccordionGroup>
  <Accordion icon="key" title="401 Unauthorized">
    常见原因是没有传 `Bearer Token`、Token 失效，或请求头格式错误。先检查 `Authorization` 是否完整。
  </Accordion>

  <Accordion icon="shield-exclamation" title="403 Forbidden">
    一般表示当前凭证没有权限访问对应资源，或访问被策略限制。请先确认账号配置和请求范围。
  </Accordion>

  <Accordion icon="circle-exclamation" title="400 Bad Request">
    常见于请求体结构错误、字段类型不对、缺少必填参数，或模型名填写无效。
  </Accordion>

  <Accordion icon="hourglass-half" title="429 Too Many Requests">
    表示请求过于频繁或超出限制。可以降低并发、增加重试退避，或稍后再发起请求。
  </Accordion>

  <Accordion icon="triangle-exclamation" title="500 / 502 / 503">
    这类通常是服务端异常或上游暂时不可用。建议记录请求参数，稍后重试，并保留错误响应用于排查。
  </Accordion>
</AccordionGroup>

<CardGroup cols={1}>
  <Card title="文本对话接口" icon="messages" href="/api-reference/chat-completions">
    查看 `/chat/completions` 的用途、请求参数、响应示例、流式返回说明和排错建议。
  </Card>
</CardGroup>

<Tip>
  如果你已有 OpenAI 兼容代码，最常见的改动只有三项：Base URL、API Key 和模型名。
</Tip>