> ## 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.

# OpenAI 格式

> 用兼容 OpenAI 的方式，快速发起第一条智牛API 文本对话请求。

## 准备内容

开始前，你只需要准备三样东西：

* `API Key`
* 固定 Base URL：`https://niuapi.vip/v1`
* 一个兼容 OpenAI 调用方式的客户端或 SDK

<Note>
  智牛API 当前文档聚焦文本对话能力，本文示例统一使用 `https://niuapi.vip/v1` 作为 Base URL。
</Note>

## 一次最小可用请求

请求本质上很简单：带上 `Authorization: Bearer <API Key>`，向 `/chat/completions` 发送模型名和 `messages`。

```bash theme={null}
curl https://niuapi.vip/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "你好，请用一句话介绍智牛API。"
      }
    ]
  }'
```

## Python 示例

如果你已经在用官方 OpenAI Python SDK，迁移会很顺手。核心就是把 `base_url` 指向智牛API。

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

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://niuapi.vip/v1")

completion = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "你是一个简洁的助手。"},
        {"role": "user", "content": "帮我写一句产品介绍。"}
    ]
)

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

## JavaScript 示例

官方 OpenAI Node SDK 也可以直接按兼容方式使用，注意这里的字段名是 `baseURL`。

```javascript theme={null}
import OpenAI from "openai"

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://niuapi.vip/v1"
})

const completion = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    { role: "system", content: "你是一个简洁的助手。" },
    { role: "user", content: "帮我总结一下文本对话接口怎么接。" }
  ]
})

console.log(completion.choices[0].message.content)
```

## 你需要知道的三个关键点

<AccordionGroup>
  <Accordion icon="box" title="model 是什么">
    `model` 用来指定你要调用的模型。它必须是当前可用且填写正确的模型名。模型名写错时，请求通常会直接失败。
  </Accordion>

  <Accordion icon="messages" title="messages 是什么">
    `messages` 是对话上下文数组。你可以放 `system`、`user`、`assistant` 等角色内容。单轮对话放一条 `user` 消息就够，多轮对话则按顺序追加历史消息。
  </Accordion>

  <Accordion icon="key" title="Authorization 是什么">
    所有请求都需要通过 `Authorization: Bearer YOUR_API_KEY` 传递密钥。没有 Key、Key 无效，或格式写错，接口都不会正常返回结果。
  </Accordion>
</AccordionGroup>

## 常见问题

<AccordionGroup>
  <Accordion icon="link" title="请求发到了错误的 URL">
    请确认 Base URL 固定为 `https://niuapi.vip/v1`。常见错误包括漏掉 `/v1`、把完整接口路径写进 SDK 的 Base URL，或者仍然指向别的服务地址。
  </Accordion>

  <Accordion icon="shield-exclamation" title="没有传 API Key 或 Key 无效">
    检查 `Authorization` 请求头是否为 `Bearer YOUR_API_KEY` 格式。注意不要漏掉 `Bearer` 前缀，也不要把占位符直接拿去跑生产请求。
  </Accordion>

  <Accordion icon="circle-exclamation" title="模型名无效">
    如果返回模型不存在、不可用或参数错误，先检查 `model` 是否填写为当前支持的有效名称。不要想当然沿用旧项目里的模型名。
  </Accordion>
</AccordionGroup>

<Tip>
  如果你已经有基于 OpenAI SDK 的代码，通常只需要改三处：`API Key`、Base URL，以及模型名。
</Tip>

## 下一步

<CardGroup cols={2}>
  <Card title="API 总览" icon="book-open" href="/api-reference/introduction">
    先了解认证方式、请求约定、状态码和错误结构。
  </Card>

  <Card title="文本对话接口" icon="square-terminal" href="/api-reference/chat-completions">
    继续查看 `/chat/completions` 的完整参数说明和返回示例。
  </Card>
</CardGroup>