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

# 输出图片保存

> 返回 URL、base64、文件有效期和自建存储建议

图片接口通常返回 URL 或 base64。生产环境不要假设返回 URL 永久有效，建议尽快转存到自己的对象存储。

## 返回格式

| 格式         | 适合                         | 注意                             |
| ---------- | -------------------------- | ------------------------------ |
| `url`      | 大多数服务端应用，便于下载后转存           | URL 可能是 Tapapi 代理地址，也可能是上游临时地址 |
| `b64_json` | 内网处理、队列任务、无法直接访问外部 URL 的场景 | 响应体会明显变大，前端直传容易超时              |

## URL 返回

```json theme={null}
{
  "created": 1780000000,
  "data": [
    {
      "url": "https://tapapi.ai/img-proxy/..."
    }
  ]
}
```

Tapapi 可能会隐藏或代理上游图片地址，避免直接暴露上游临时 URL。代理地址不是长期图库：当前默认按短期签名 URL 处理，后续也可能按渠道调整。业务系统应该把结果保存到自己的 COS、S3、R2 或 OSS。

<Note>部分官方直连渠道可能会透传上游 URL；部分模型即使请求 `response_format: "url"`，也可能按上游能力返回 `b64_json`。生产代码需要同时处理两种返回字段。</Note>

<Warning>拿到图片 URL 后没有下载成功，不等于模型生成失败。模型已经返回有效图片时通常会正常计费，所以生产系统要尽快转存并记录保存状态。</Warning>

## Base64 返回

```json theme={null}
{
  "created": 1780000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgo..."
    }
  ]
}
```

`b64_json` 会让响应体明显变大，适合内网处理、队列任务或不方便访问外部图片 URL 的场景。

## 推荐流程

1. 调用 Tapapi 生成图片
2. 拿到返回 URL 或 base64
3. 如果是 URL，后端服务下载图片；如果是 base64，后端解码图片
4. 上传到自己的 COS、S3、R2 或 OSS
5. 在业务数据库里保存自有图片 URL
6. 保存业务 `task_id`、模型名、请求参数、返回字段和错误码，方便后续对账和排障
7. 保存请求的 `n` 和实际返回的 `data.length`
8. 保存响应头 `X-Oneapi-Request-Id`

## 生产保存建议

| 场景           | 推荐                          |
| ------------ | --------------------------- |
| Web / App 展示 | 先转存到自有对象存储，再把自有 URL 返回给前端   |
| 批量跑图         | 每张图单独记录保存状态，失败的图片单独重跑       |
| 电商商品图        | 保存原图、压缩图和业务素材 ID，避免后续找不到来源  |
| 内部工作流        | 可以先落队列或数据库，但要限制 base64 字段体积 |

## 排障点

* URL 下载失败：先确认服务端能访问该 URL，不要只在浏览器里测试
* `img-proxy` 下载失败：可能是签名过期、上游取图失败或访问策略拦截，尽快用服务端重试并保留错误
* base64 解码失败：确认没有把 `data:image/png;base64,` 前缀和纯 base64 混用
* 返回字段不是预期：同时兼容 `url` 和 `b64_json`，不要只写死一种字段
* 批量保存失败：记录每张图的业务 `task_id`、模型、prompt、返回字段和错误码
* 部分成功：检查 `metadata.tapapi_partial`、`requested_n`、`returned_n` 和 `failed_requests`