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

# API 参考说明

> 如何阅读自动生成的图片 API Reference

API Reference 由 OpenAPI schema 生成，适合查询字段、请求体和响应体。第一次接入不要从 API Reference 开始，先按教程跑通最小请求，再回来查字段。

<Warning>schema 里出现某个字段，不代表它对所有模型都是稳定生产能力。正文教程和模型详情页写明“未开放”“条件可用”“按模型确认”的字段，不要直接复制到生产请求里。</Warning>

## 推荐阅读顺序

1. 先看 [快速开始](/quickstart)，确认 API Key、base URL 和模型名可用。
2. 文生图看 [文生图](/image-generation/text-to-image)。
3. 查字段含义看 [参数说明](/image-generation/parameters)。
4. 再用本页下方的 API Reference 查请求体和响应体。
5. 上线前看 [错误码与重试](/errors)、[输出图片保存](/image-generation/output-images) 和 [上线 Checklist](/production/launch-checklist)。

## 当前 Reference 覆盖

| Endpoint                          | 状态   | 说明                                        |
| --------------------------------- | ---- | ----------------------------------------- |
| `POST /v1/images/generations`     | 稳定主线 | OpenAI-compatible 文生图                     |
| `POST /v1/tapapi/images/advanced` | 有边界  | 当前主要用于已确认字段；`image_urls` / `webhook` 会被拦截 |
| `POST /v1/images/edits`           | 条件可用 | 仅模型明确支持图片编辑协议时使用                          |

## 字段口径

| 字段类型   | 处理方式                                                 |
| ------ | ---------------------------------------------------- |
| 稳定字段   | 可以按教程接入，例如 `model`、`prompt`、`size`、`response_format` |
| 条件字段   | 先看模型详情页，例如 `quality`、`output_format`、`extra_fields`  |
| 图片输入字段 | 只在图片编辑或模型明确支持时使用                                     |
| 未开放字段  | 不要传入生产请求，例如 advanced 的 `image_urls`、`webhook`        |

## 排查建议

* 返回 400 / 422：先检查字段是否属于当前 endpoint 和当前模型。
* 返回空 `data`：按生成失败处理，保留请求参数、模型名、业务 `task_id` 和 `X-Oneapi-Request-Id`。
* `n > 1` 返回数量不足：检查 `metadata.tapapi_partial`、`requested_n`、`returned_n` 和 `failed_requests`。
* 只有 `b64_json`：解码后转存，不要只读取 `url`。
* 返回 URL：尽快转存到自己的对象存储，不要长期依赖临时链接或代理链接。
* 联系支持：带上 HTTP 状态码、错误对象、模型名、请求时间和 `X-Oneapi-Request-Id`。