路径 2 · 高级 - Tapapi 文档

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

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

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

当前适合做什么

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

当前可用字段

字段	类型	必填	默认	说明
`model`	string	✅	—	模型名（见模型清单）
`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。

示例

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`	不作为通用公开字段承诺	使用模型详情明确说明的字段

这页的定位是“高级入口边界说明”，不是图生图教程。图生图正式开放后，会在图生图单独给出稳定示例。

上线前检查

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