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

# OpenAI

> OpenAI 兼容 HTTP 接口说明与多语言调用示例。

> 这里只保留 OpenAI 兼容 HTTP 接口说明，以及 cURL、Python、Node.js 的直接调用示例。

## 接口摘要

| Endpoint                    | Summary                          |
| --------------------------- | -------------------------------- |
| `POST /v1/chat/completions` | 用于标准聊天补全调用，适合多轮对话、工具调用和流式返回。     |
| `POST /v1/responses`        | 用于新版统一响应接口，适合结构化输出、多模态输入和后续能力扩展。 |

## `POST /v1/chat/completions`

用于标准聊天补全调用，适合多轮对话、工具调用和流式返回。

### 请求说明

* 使用 Authorization: Bearer {API_KEY} 进行鉴权，请求体核心字段为 model 与 messages。
* messages 按角色顺序传入 system、user、assistant 历史；如需流式返回，额外设置 stream=true。
* 如果网关兼容 OpenAI 协议，这个接口通常是最稳妥的默认接入入口。

### 响应说明

* 同步结果一般从 choices\[0].message.content 读取。
* 如果模型触发工具调用，需要同时处理 tool\_calls 和后续工具结果回传。
* 流式模式下返回的是 SSE chunk，而不是一次性完整 JSON。

### 调用示例

#### cURL

chat.completions

```bash theme={null}
curl --request POST \
  --url https://api.tokenops.ai/v1/chat/completions \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-4.1-mini",
    "messages": [
      { "role": "system", "content": "You are a concise API assistant." },
      { "role": "user", "content": "给我一个联系表单字段定义。" }
    ]
  }'
```

#### Python

requests

```python theme={null}
import requests

response = requests.post(
    'https://api.tokenops.ai/v1/chat/completions',
    headers={
        'Authorization': 'Bearer ${YOUR_API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'model': 'gpt-4.1-mini',
        'messages': [
            {'role': 'system', 'content': 'You are a concise API assistant.'},
            {'role': 'user', 'content': '给我一个联系表单字段定义。'}
        ]
    },
    timeout=60
)

print(response.json())
```

#### Node.js

fetch

```javascript theme={null}
const response = await fetch('https://api.tokenops.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ${YOUR_API_KEY}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4.1-mini',
    messages: [
      { role: 'system', content: 'You are a concise API assistant.' },
      { role: 'user', content: '给我一个联系表单字段定义。' }
    ]
  })
})

console.log(await response.json())
```

### 响应示例 (200)

response

```json theme={null}
{
  "id": "chatcmpl_123",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"name\":\"email\",\"type\":\"string\"}"
      }
    }
  ]
}
```

## `POST /v1/responses`

用于新版统一响应接口，适合结构化输出、多模态输入和后续能力扩展。

### 请求说明

* 同样使用 Bearer Token 鉴权，但请求体主体从 messages 转为 input 与 instructions 等字段。
* 如果你要统一文本与结构化结果输出，优先考虑这个接口而不是旧的 chat.completions。
* response\_format、工具定义和多模态输入通常也会优先在这一支接口演进。

### 响应说明

* 返回结构通常从 output\[] 或 output\_text 中读取，而不是 choices\[0].message。
* 当接口进入异步或工具编排模式时，状态字段会比旧接口更丰富。
* 迁移时应同时检查服务端日志、重试逻辑和字段映射。

### 调用示例

#### cURL

responses

```bash theme={null}
curl --request POST \
  --url https://api.tokenops.ai/v1/responses \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-4.1-mini",
    "input": "给我一个联系人字段定义，返回 JSON。"
  }'
```

#### Python

requests

```python theme={null}
import requests

response = requests.post(
    'https://api.tokenops.ai/v1/responses',
    headers={
        'Authorization': 'Bearer ${YOUR_API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'model': 'gpt-4.1-mini',
        'input': '给我一个联系人字段定义，返回 JSON。'
    },
    timeout=60
)

print(response.json())
```

#### Node.js

fetch

```javascript theme={null}
const response = await fetch('https://api.tokenops.ai/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ${YOUR_API_KEY}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4.1-mini',
    input: '给我一个联系人字段定义，返回 JSON。'
  })
})

console.log(await response.json())
```

### 响应示例 (200)

response

```json theme={null}
{
  "id": "resp_123",
  "status": "completed",
  "output": [
    {
      "type": "output_text",
      "text": "{\"name\":\"email\",\"type\":\"string\"}"
    }
  ]
}
```