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

# 核心概念

> base_url、API Key、model、余额和失败不扣

这页解释 Tapapi 文档里反复出现的几个基础概念。先理解这些词，后面的 API、计费和排障会顺很多。

## base\_url

`base_url` 是 SDK 或 HTTP 请求指向的 API 根地址。Tapapi 的 OpenAI 兼容入口是：

```text theme={null}
https://tapapi.ai/v1
```

已有 OpenAI SDK 项目通常只需要把 `base_url` 改成这个地址，再换成 Tapapi 的 API Key。

## API Key

API Key 用于鉴权，放在请求头：

```http theme={null}
Authorization: Bearer sk-xxx
```

不要把 API Key 放进前端代码、公开仓库、公开截图或客户端直连配置里。需要前端调用时，建议先经过自己的后端代理。

## model

`model` 决定调用哪个模型。文本、图片和视频模型都会通过 `model` 字段区分。大多数情况下，切换模型只需要修改 `model`，不需要重写整套调用代码。

可用模型以控制台和 [模型中心](/models/choose-model) 为准。

## 文本模型

文本模型通常走：

```text theme={null}
POST /v1/chat/completions
```

适合聊天、摘要、改写、翻译、代码、分类和自动化任务。返回内容通常在 `choices[0].message.content`。

## 图片模型

图片生成通常走：

```text theme={null}
POST /v1/images/generations
```

适合文生图和基础图片生成。返回结果通常在 `data[0].url`，也可能是 `data[0].b64_json`。生产环境要兼容两种字段，并尽快把图片转存到自己的对象存储。更复杂的图片能力请看 [图片 API](/image-generation/overview)，不同模型支持范围可能不同。

## 视频模型

视频 API 当前按受控开放维护。平台已具备视频任务、轮询和输出获取能力，但生产前必须确认控制台可见模型、账号权限、价格和具体模型文档。

## OpenAI 兼容

OpenAI 兼容表示：你可以继续使用 OpenAI SDK 或 OpenAI-compatible 工具，只替换 `base_url`、`api_key` 和 `model`。兼容不代表每个上游私有参数都完全一致；生产接入前仍需用真实请求测试。

## 余额与计费

Tapapi 按实际调用计费。系统内部使用 `quota` 作为额度单位，控制台会展示余额、已用额度和请求记录。不同模型、账户分组、输入输出长度、图片张数和任务结果都会影响最终消耗。

完整规则见 [价格说明](/pricing)、[计费与退款](/billing) 和 [余额与用量](/account/balance-usage)。

## 失败不扣

失败不扣看最终结算结果：平台或上游失败、连接中断、没有生成结果的超时，最终不应扣费；如果模型已经成功返回有效结果，则通常正常计费。上线前请看 [失败不扣规则](/production/failure-refund) 和 [错误码与重试](/errors)。

## 同步与异步

同步请求会在一次 HTTP 响应里直接返回结果。异步任务通常需要先提交任务，再轮询任务状态。文本和普通图片请求优先按同步路径理解；耗时更长的视频和部分长任务以后续专题为准。

## request id

每次请求都会有请求标识。Tapapi 会在响应头返回：

```http theme={null}
X-Oneapi-Request-Id: 20260609...
```

遇到报错、超时、账单问题或图片下载问题时，保留 request id、模型名、时间、HTTP 状态码和错误信息，可以更快定位问题。通过后端代理调用时，也建议把这个 request id 写入自己的业务日志。