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

# 参数说明

> 生图常用字段、默认值和模型差异

这页集中解释图片生成参数。具体模型是否支持某个字段，以控制台和模型详情页为准；不确定的字段不要直接写进生产请求。

## 稳定字段

| 字段                | 用途   | 说明                                        |
| ----------------- | ---- | ----------------------------------------- |
| `model`           | 选择模型 | 必填                                        |
| `prompt`          | 提示词  | 必填                                        |
| `n`               | 生成张数 | 默认 1；批量建议优先用业务侧单张循环                       |
| `size`            | 图片尺寸 | 不同模型支持范围不同；使用 `1024x1024`，不要写 `1024×1024` |
| `response_format` | 返回格式 | `url` / `b64_json`                        |

## 条件字段

| 字段                                                 | 当前状态 | 说明                                   |
| -------------------------------------------------- | ---- | ------------------------------------ |
| `quality`                                          | 条件可用 | 部分模型支持质量档位                           |
| `output_format`                                    | 条件可用 | 部分模型支持 `png` / `jpeg` / `webp`       |
| `extra_fields`                                     | 条件可用 | 仅在模型详情明确说明时使用                        |
| `seed`                                             | 条件可用 | 部分上游支持复现；未确认前不要当成通用字段                |
| `mask`                                             | 条件可用 | 只在 `/v1/images/edits` 且模型明确支持局部编辑时使用 |
| `image` / `image[]`                                | 条件可用 | 只在 `/v1/images/edits` 或模型明确支持图片输入时使用 |
| `background` / `moderation` / `output_compression` | 条件可用 | OpenAI 风格扩展字段，需按模型验证                 |

## 当前不要传的字段

| 字段           | 为什么                                 |
| ------------ | ----------------------------------- |
| `image_urls` | advanced 路径会在计费前拦截；不要用于图生图或多参考图生产请求 |
| `webhook`    | 图片 webhook 当前不是公开稳定能力；请用业务侧队列和轮询    |
| 未确认私有字段      | 不同模型字段差异很大，未确认时可能 400、无效或被上游忽略      |

## 成本提醒

`n`、尺寸、质量档位都会影响成本或成功率。批量跑图前，先用 20-50 条真实 prompt 做小样本测试，再放大并发。

Tapapi 会按实际返回图片数量结算并封顶到请求的 `n`。如果上游 200 但 `data` 为空，应按生成失败排查，不要只看 HTTP 状态码。

## 日志字段

图片请求至少记录这些字段，方便排障和对账：

| 字段                                        | 用途                |
| ----------------------------------------- | ----------------- |
| `model` / `prompt` / `size` / `n`         | 复现请求和评估成本         |
| `response_format` / 实际返回字段                | 判断是 URL 还是 base64 |
| `data.length`                             | 判断是否空结果或部分成功      |
| `metadata.tapapi_partial`                 | 判断 fan-out 是否部分失败 |
| HTTP 状态码 / `error.code` / `error.message` | 分类失败原因            |
| `X-Oneapi-Request-Id`                     | 联系 Tapapi 排查时定位请求 |