# 代码集成

TokenFlows 兼容常用 OpenAI SDK 调用方式。大多数项目只需要替换 `base_url` / `baseURL` 和 API Key，即可接入 TokenFlows。

## 前置条件

- 一个有效的 [TokenFlows 账号](https://dash.tokenflows.org/)
- 一个 TokenFlows API Key
- 一个要调用的模型 ID，可在 [模型列表](/models) 查看

## 端点选择

| 协议 | Base URL | 适用场景 |
| --- | --- | --- |
| OpenAI 兼容协议 | `https://api.tokenflows.org/v1` | OpenAI SDK、Chat Completions、Responses API |
| Anthropic 兼容协议 | `https://api.tokenflows.org` | Claude Code 环境变量、Anthropic Messages 路径 |

> Claude Code 的 `ANTHROPIC_BASE_URL` 不要加 `/v1`；如果你是直接发 HTTP 请求，请调用完整路径 `https://api.tokenflows.org/v1/messages`。

## 安装 SDK

```bash
# Python
pip install openai

# Node.js / TypeScript
npm install openai

# Go
go get github.com/openai/openai-go
```

建议把密钥放入环境变量，避免写死在代码里：

```bash
export TOKENFLOWS_API_KEY="YOUR_API_KEY"
```

## Chat Completions

适合已有 OpenAI Chat Completions 代码迁移。

### Python

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.tokenflows.org/v1",
    api_key=os.environ["TOKENFLOWS_API_KEY"],
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {"role": "user", "content": "你好，介绍一下 TokenFlows"}
    ],
)

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

### Node.js / TypeScript

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.tokenflows.org/v1',
  apiKey: process.env.TOKENFLOWS_API_KEY,
});

const response = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [
    { role: 'user', content: '你好，介绍一下 TokenFlows' },
  ],
});

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

## Responses API

GPT 系列和部分 Agent 工具推荐使用 Responses API。它更适合推理、工具调用和多模态工作流。

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.tokenflows.org/v1',
  apiKey: process.env.TOKENFLOWS_API_KEY,
});

const response = await client.responses.create({
  model: 'gpt-5.5',
  input: '用三句话介绍 TokenFlows',
});

console.log(response.output_text);
```

## Anthropic Messages

如果你的项目使用 Claude 协议，可直接请求 Messages API：

```bash
curl -X POST https://api.tokenflows.org/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "你好，介绍一下 TokenFlows"}
    ]
  }'
```

## 常见注意事项

- `YOUR_API_KEY` 只用于服务端或本地可信环境，不要暴露到前端页面。
- 模型 ID 必须与 [模型列表](/models) 中展示的一致。
- Agent 工具会读取上下文并产生额外 token，费用可能高于普通单轮聊天。
- 遇到 `401` 先检查 API Key、余额和套餐状态；遇到网络类错误可参考 [常见问题](/docs/faq)。