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

# 路径 2 · 高级

> POST /v1/tapapi/images/advanced · 高级图片入口和当前边界

`/v1/tapapi/images/advanced` 是 Tapapi 的高级图片入口。当前它复用图片生成链路，并在上游转发时归一到 `/v1/images/generations`；公开稳定能力仍以文生图为主。

<Warning>`image_urls` 和 `webhook` 当前会在计费前被拦截并返回 400。不要把 advanced 当作稳定图生图、多参考图或 webhook 入口。</Warning>

```
POST https://tapapi.ai/v1/tapapi/images/advanced
```

## 当前适合做什么

| 场景             | 当前建议                               |
| -------------- | ---------------------------------- |
| 普通文生图          | 优先使用 `/v1/images/generations`      |
| 已接入高级路径的内部测试   | 可以用纯文本 prompt 验证模型路由               |
| 模型私有参数         | 仅在模型详情明确说明时使用 `extra_fields` 或约定字段 |
| 图生图 / 多参考图     | 当前不要传 `image_urls`，会被计费前拦截         |
| webhook / 异步回调 | 当前不要传 `webhook`，用业务侧队列实现异步体验       |

## 当前可用字段

| 字段                | 类型     |  必填 | 默认    | 说明                                       |
| ----------------- | ------ | :-: | ----- | ---------------------------------------- |
| `model`           | string |  ✅  | —     | 模型名（见[模型清单](/image-generation/overview)） |
| `prompt`          | string |  ✅  | —     | 提示词                                      |
| `n`               | int    |  —  | 1     | 一次生成几张；模型支持范围不同                          |
| `size`            | string |  —  | 模型自定  | 例如 `1024x1024`、`1536x1024`               |
| `quality`         | string |  —  | 模型自定  | 部分模型支持                                   |
| `output_format`   | enum   |  —  | 模型自定  | `png` / `jpeg` / `webp`，仅部分模型支持          |
| `response_format` | enum   |  —  | `url` | `url` / `b64_json`                       |
| `extra_fields`    | object |  —  | `{}`  | 条件字段；仅在模型详情明确说明时使用                       |

## 为什么拦截 `image_urls`

高级入口当前会归一到标准文生图路径。如果透传 `image_urls`，部分上游可能忽略参考图、返回空结果甚至产生无效成本。Tapapi 会在计费前拦截这类请求，避免“参考图没有生效但仍进入计费链路”。

被拦截时会返回 400，并在错误对象里说明字段暂未开放。排查时保存 `error.message`、HTTP 状态码和响应头 `X-Oneapi-Request-Id`。

## 示例

```bash theme={null}
curl https://tapapi.ai/v1/tapapi/images/advanced \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image-turbo",
    "prompt": "a red apple on a wooden table",
    "size": "1024x1024",
    "response_format": "url"
  }'
```

## 暂不开放字段

| 字段           | 当前状态        | 正确处理             |
| ------------ | ----------- | ---------------- |
| `image_urls` | 当前会被拦截      | 不要用于图生图或多参考图生产请求 |
| `webhook`    | 当前会被拦截      | 先使用同步返回或业务侧队列    |
| `extra`      | 不作为通用公开字段承诺 | 使用模型详情明确说明的字段    |

<Note>这页的定位是“高级入口边界说明”，不是图生图教程。图生图正式开放后，会在 [图生图](/image-generation/image-to-image) 单独给出稳定示例。</Note>

## 上线前检查

* 普通文生图能否先用 `/v1/images/generations` 完成
* `extra_fields` 是否在目标模型详情里明确出现
* `n > 1` 时是否正确处理部分成功和空 `data`
* 日志是否保存模型名、请求参数、错误对象、耗时和 `X-Oneapi-Request-Id`
* 是否避免把 `image_urls`、`webhook` 当成当前稳定能力