AI 根据透明前景 PNG 图片和背景提示词或模板 ID，生成自然匹配的背景结果图。适用于商品图、营销海报、设计素材等场景。当前支持异步调用方式。
接口返回的链接有效期为 1 小时，请及时下载存储。
鉴权
每个 API 请求都必须在请求头中携带你的 API Key。请按当前文档中的请求方式和参数说明，将其作为 X-API-KEY 请求头传入。
X-API-KEY: YOUR_API_KEY 创建图片背景生成任务
POST
/api/tasks/visual/r-background 请求参数
image_url string 可选 源图像 URL。如果存在此参数，则其他图像源参数必须为空。
二选一必填
batch_size integer 可选 每次生成图片数，默认值为 2，目前仅支持 1 或 2。
prompt string 可选 背景提示词，支持多语言，但英文效果最好，最长 1024 个字符。
二选一必填
scene_type integer 可选 背景模板 ID。可通过 scene_type API 获取最新模板 ID。prompt、scene_type 二选一。
negative_prompt string 可选 负面关键词，支持多语言，但英文效果最好。
返回参数
status number HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见 状态码说明。
message string 返回说明。任务失败时可参考此字段或联系客服。
data.task_id string 图片背景生成任务 ID，用于轮询结果。
查询图片背景生成结果
异步请求建议每 1 秒 轮询一次结果，本接口最大轮询时长为 120 秒；累计轮询超过该时长仍未返回结果，即可视为超时失败。
GET
/api/tasks/visual/r-background/{task_id} 路径参数
task_id string 必填 创建图片背景生成任务后返回的任务 ID，用于查询任务处理结果。
返回参数
status number HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败，详见 状态码说明。
message string 返回说明。任务失败时可参考此字段或联系客服。
data.task_id string 图片背景生成任务 ID。如果任务失败，请携带此参数联系客服。
data.created_at string 任务创建时间戳。
data.processed_at string 任务开始处理时间戳。
data.completed_at string 任务完成时间戳。
data.image_1 string 背景生成结果图片 1 的下载 URL 或 Base64 数据。
data.image_2 string 背景生成结果图片 2 的下载 URL 或 Base64 数据。
data.progress number 任务处理进度。
data.state number 任务处理状态。1 表示成功，大于 1 表示处理中，小于 0 表示失败。-7 表示无效图片文件，详见 状态码说明。
data.return_type number 结果返回方式。
data.state_detail string 任务处理状态详情。
data.time_elapsed number 用时，单位毫秒。
使用规范与限制
-
接口返回的链接有效期为 1 小时，请及时下载存储。
-
HTTP status 为 200 表示 HTTP 请求成功，并非背景生成成功，任务结果请结合 data.state 判断，详见 状态码说明。
-
输入图片最小分辨率为 256x256，最大分辨率为 4096x4096，且必须是仅包含前景的透明 PNG 图片。
-
输出图片最大分辨率为 1024x1024，并保持原图比例。
-
上传图片需符合以下格式、分辨率和大小限制。
格式 分辨率 大小 png 最大 4096x4096 最大20MB
查看 Markdown
# 图片背景生成 API
通过 API 为透明前景 PNG 图片生成 AI 背景。提供背景提示词或 scene_type 模板后，接口会返回任务 ID，并通过轮询获取生成结果图。
> 注意：接口返回的链接有效期为 1 小时，请及时下载存储。
## 接口域名（Base URL）
以下路径均基于接口域名：
```
https://techsz.aoscdn.com
```
## 鉴权
每个请求都必须在请求头中携带你的 API Key：
```http
X-API-KEY: YOUR_API_KEY
```
你可以在 [API Key](https://picwish.cn/my-account?subRoute=api-key) 页面获取或管理 X-API-KEY。
未携带有效 API Key 的请求会被拒绝。
## 调用方式
该接口当前使用异步处理。创建接口返回 `data.task_id`，随后使用该任务 ID 查询生成结果。
请求成功后，结果最多只会保留 1 小时。
## 原图与背景描述
必须提供一种原图来源，`image_url` / `image_file` 二者互斥：
- `image_url`：源图像 URL。如果存在此参数，则其他图像源参数必须为空。
- `image_file`：源图像文件（二进制）。如果此参数存在，则其他图像源参数必须为空。
同时必须提供一种背景描述，`prompt` / `scene_type` 二选一：
- `prompt`：背景提示词，支持多语言，但英文效果最好，最长 1024 个字符。
- `scene_type`：背景模板 ID。可通过 [scene_type API](https://picwish.cn/background-sceneid-api-doc) 获取最新模板 ID。
## 接口列表
| 用途 | 请求方式 | 路径 |
| --- | --- | --- |
| 创建图片背景生成任务 | POST | /api/tasks/visual/r-background |
| 查询任务结果 | GET | /api/tasks/visual/r-background/{task_id} |
## 创建图片背景生成任务
`POST /api/tasks/visual/r-background`
Content-Type: `multipart/form-data`
### 请求参数
| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| image_url | string | image_url / image_file 二选一 | 源图像 URL。如果存在此参数，则 image_file 必须为空。 |
| image_file | file | image_url / image_file 二选一 | 源图像文件（二进制）。如果此参数存在，则 image_url 必须为空。 |
| batch_size | integer | 可选 | 每次生成图片数，目前仅支持 1 或 2，默认值为 2。 |
| prompt | string | prompt / scene_type 二选一 | 背景提示词，支持多语言，但英文效果最好，最长 1024 个字符。 |
| scene_type | integer | prompt / scene_type 二选一 | 背景模板 ID，可通过 scene_type API 获取最新模板 ID。 |
| negative_prompt | string | 可选 | 负面关键词，支持多语言，但英文效果最好。 |
### 返回参数
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| status | number | HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败。详见 /states。 |
| message | string | 返回说明。任务失败时可参考此字段或联系客服。 |
| data.task_id | string | 任务 ID，用于轮询结果。 |
### 示例
异步，使用图片 URL 和 scene_type：
```bash
curl -k 'https://techsz.aoscdn.com/api/tasks/visual/r-background' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'scene_type=105' \
-F 'image_url=YOUR_IMAGE_URL'
```
异步，上传本地图片文件并使用 scene_type：
```bash
curl -k 'https://techsz.aoscdn.com/api/tasks/visual/r-background' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'scene_type=105' \
-F 'image_file=@/path/to/image.png'
```
异步创建响应示例：
```json
{
"status": 200,
"message": "success",
"data": { "task_id": "TASK_ID" }
}
```
## 查询图片背景生成结果
异步请求建议每 **1 秒** 轮询一次结果，本接口最大轮询时长为 **120 秒**；累计轮询超过该时长仍未返回结果，即可视为超时失败。
`GET /api/tasks/visual/r-background/{task_id}`
用于轮询获取生成结果图。
### 路径参数
| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| task_id | string | 必填 | 创建图片背景生成任务后返回的任务 ID。 |
### 返回参数
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| status | number | HTTP 响应状态码。200 表示请求成功，非 200 表示请求失败。详见 /states。 |
| message | string | 返回说明。任务失败时可参考此字段或联系客服。 |
| data.task_id | string | 任务 ID。如果任务失败，请携带此参数联系客服。 |
| data.created_at | string | 任务创建时间戳。 |
| data.processed_at | string | 任务开始处理时间戳。 |
| data.completed_at | string | 任务完成时间戳。 |
| data.image_1 | string | 背景生成结果图片 1 的下载 URL 或 Base64 数据。 |
| data.image_2 | string | 背景生成结果图片 2 的下载 URL 或 Base64 数据。 |
| data.progress | number | 任务处理进度。 |
| data.state | number | 任务处理状态。1 表示成功，大于 1 表示处理中，小于 0 表示失败；-7 表示无效图片文件。详见 /states。 |
| data.return_type | number | 结果返回方式。 |
| data.state_detail | string | 任务处理状态详情。 |
| data.time_elapsed | number | 用时，单位毫秒。 |
### 示例
```bash
curl -k 'https://techsz.aoscdn.com/api/tasks/visual/r-background/{task_id}' \
-H 'X-API-KEY: YOUR_API_KEY'
```
处理完成响应示例：
```json
{
"status": 200,
"message": "success",
"data": {
"task_id": "TASK_ID",
"state": 1,
"progress": 100,
"image_1": "https://.../image_1.jpg",
"image_2": "https://.../image_2.jpg",
"completed_at": "1634884056"
}
}
```
## 推荐异步流程
1. 使用一种原图来源以及 `prompt` 或 `scene_type` POST 到 /api/tasks/visual/r-background。
2. 从创建响应中读取 `data.task_id`。
3. 每 1 秒 GET /api/tasks/visual/r-background/{task_id}，整体轮询时长建议不超过 120 秒。
4. 检查 `data.state`：1 = 完成（读取 `data.image_1` / `data.image_2`）；大于 1 = 继续轮询；小于 0 = 失败。
5. 在 1 小时内下载生成结果图。
## 使用规范与限制
- 接口返回的链接有效期为 **1 小时**，请及时下载存储。
- HTTP status 为 200 表示 HTTP 请求成功，并非背景生成成功，任务结果请结合 data.state 判断，详见状态码说明。
- 输入图片最小分辨率为 256x256，最大分辨率为 4096x4096，且必须是仅包含前景的透明 PNG 图片。
- 输出图片最大分辨率为 1024x1024，并保持原图比例。
- 每次成功调用消耗 3~10 算粒：1 张 = 3 算粒，2 张 = 6 算粒，3 张 = 8 算粒，4 张 = 10 算粒。
- 上传图片需符合以下格式、分辨率和大小限制。
| 格式 | 分辨率 | 大小 |
| --- | --- | --- |
| png | 最大 4096x4096 | 最大20MB |
## 状态码
任务是否成功，需要结合 HTTP 响应状态码（`status`）和任务状态码（`data.state`）共同判断。
### HTTP 响应状态码
| 状态码 | 说明 |
| --- | --- |
| 200 | 请求成功。 |
| 400 | 客户端参数传递错误。请检查参数是否缺失或值是否正确。 |
| 401 | 认证失败。请检查 X-API-KEY 是否正确或服务是否开通。 |
| 404 | 请求的 URL 或资源不存在。请检查 URL 或 task_id 是否正确。 |
| 413 | 上传的文件超出大小限制。请参见各服务的最大文件限制。 |
| 429 | 请求频率超出 QPS 限制（默认 QPS 为 2）。请放缓请求速率，或联系商务提升 QPS。 |
| 500 | 服务端异常。请反馈给商务或技术对接人员。 |
### 任务状态码（data.state）
1 = 成功；大于 1 = 处理中；小于 0 = 失败。
| 状态码 | 说明 |
| --- | --- |
| -17 | 处理失败，非法提示词。 |
| -16 | 处理失败，使用第三方检测发现违规。 |
| -15 | 处理失败，资源不足。 |
| -14 | 处理失败，输入图片内容不符合要求。 |
| -13 | 处理失败，任务异常被取消。 |
| -11 | 处理失败，结果为空。 |
| -10 | 处理失败，内部检测非法。 |
| -9 | 处理失败，内部程序循环处理失败。 |
| -8 | 处理超时，最长处理时间 180 秒。 |
| -7 | 无效图片文件（如图片损坏、格式不对等）。 |
| -5 | image_url 图片超出大小限制（30MB）。 |
| -3 | 服务器下载图片文件失败，请检查图片 URL 是否可用。 |
| -2 | 处理完成，但上传 OSS 失败。 |
| -1 | 处理失败。 |
| 0 | 排队中，任务正在队列中等待。 |
| 1 | 完成，处理成功。 |
| 2 | 准备中。 |
| 3 | 等待中。 |
| 4 | 处理中，正在进行。 |
| 5 | 内部发布处理中。 |
| 6 | 处理中，内部循环处理中。 |