使用 Ideogram 3.0 模型，根据给定的提示和可选参数同步生成图像
具体参数请看官方文档：https://developer.ideogram.ai/api-reference/api-reference/replace-background-v3
返回的图像 URL 在 24 小时内有效，超过该时间将无法访问图像。
已反代图片
POST
/ideogram/v1/ideogram-v3/replace-backgroundGenerate 3.0（替换背景） Replace Background
API Key multipart/form-data
请求示例
curl -X POST https://top.qingyuntop.ai/ideogram/v1/ideogram-v3/replace-background \
-H "Authorization: Bearer ${QINGYUN_TOP_API_KEY}"请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
Accept | Header | string | 是 | - | application/json |
Authorization | Header | string | 是 | - | Bearer {{YOUR_API_KEY}} |
image | 请求体 | file | 是 | 图像正在重新处理（最大大小为 10 兆字节）；目前仅支持 JPEG、WebP 和 PNG 格式。 | file://C:\Users\Administrator\Desktop\例子.png |
prompt | 请求体 | string | 否 | - | Add a forest in the background |
prompt | JSON body | string | 是 | 生成图像所需的提示文本 | - |
seed | JSON body | integer | 否 | 随机种子。设置此值可获得可重复的生成结果 | - |
resolution | JSON body | string: 512x1536 | 576x1408 | 576x1472 | 576x1536 | 640x1344 | 640x1408 | 640x1472 | 640x1536 | 704x1152 | 704x1216 | 704x1280 | 704x1344 | 704x1408 | 704x1472 | 736x1312 | 768x1088 | 768x1216 | 768x1280 | 768x1344 | 800x1280 | 832x960 | 832x1024 | 832x1088 | 832x1152 | 832x1216 | 832x1248 | 864x1152 | 896x960 | 896x1024 | 896x1088 | 896x1120 | 896x1152 | 960x832 | 960x896 | 960x1024 | 960x1088 | 1024x832 | 1024x896 | 1024x960 | 1024x1024 | 1088x768 | 1088x832 | 1088x896 | 1088x960 | 1120x896 | 1152x704 | 1152x832 | 1152x864 | 1152x896 | 1216x704 | 1216x768 | 1216x832 | 1248x832 | 1280x704 | 1280x768 | 1280x800 | 1312x736 | 1344x640 | 1344x704 | 1344x768 | 1408x576 | 1408x640 | 1408x704 | 1472x576 | 1472x640 | 1472x704 | 1536x512 | 1536x576 | 1536x640 | 否 | 支持的分辨率选项 | - |
aspect_ratio | JSON body | string: 1x3 | 3x1 | 1x2 | 2x1 | 9x16 | 16x9 | 10x16 | 16x10 | 2x3 | 3x2 | 3x4 | 4x3 | 4x5 | 5x4 | 1x1 | 否 | 用于图像生成的纵横比，决定图像的分辨率。不能与resolution参数同时使用。默认为1x1 | - |
rendering_speed | JSON body | string: TURBO | DEFAULT | QUALITY | 否 | 渲染速度选项 | DEFAULT |
magic_prompt | JSON body | string: AUTO | ON | OFF | 否 | 决定是否在生成请求时使用Magic Prompt | - |
negative_prompt | JSON body | string | 否 | 描述要在图像中排除的内容。提示中的描述优先于负面提示中的描述 | - |
num_images | JSON body | integer | 否 | 要生成的图像数量 | 1 |
color_palette | JSON body | object | 否 | 生成的颜色调色板，必须通过预设之一（name）或通过带有可选权重的颜色的十六进制表示（members）明确指定 | - |
style_codes | JSON body | array<string> | 否 | 表示图像风格的8字符十六进制代码列表。不能与style_reference_images或style_type一起使用 | - |
style_type | JSON body | string: AUTO | GENERAL | REALISTIC | DESIGN | 否 | 要生成的风格类型 | GENERAL |
返回响应 (200)
| 参数 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
code | 响应 JSON | integer | 是 | - | - |
message | 响应 JSON | string | 是 | - | - |
request_id | 响应 JSON | string | 是 | - | - |
data | 响应 JSON | object | 是 | - | - |
data.task_id | 响应 JSON | string | 是 | - | - |
data.task_status | 响应 JSON | string | 是 | - | - |
data.created_at | 响应 JSON | integer | 是 | - | - |
data.updated_at | 响应 JSON | integer | 是 | - | - |
响应示例
{
"code": 0,
"message": "SUCCEED",
"request_id": "CjMT7WdSwWcAAAAAALvB3g",
"data": {
"task_id": "CjMT7WdSwWcAAAAAALvB3g",
"task_status": "submitted",
"created_at": 1733851336696,
"updated_at": 1733851336696
}
}来源原始接口定义（用于追溯）
以下内容来自 Apifox 快照，可能包含兼容层字段或旧示例；公开调用请以本页的协议说明和当前模型列表为准。
{
"id": 495899663,
"name": "Generate 3.0（替换背景） Replace Background",
"type": "http",
"serverId": "",
"preProcessors": [],
"postProcessors": [],
"inheritPreProcessors": {},
"inheritPostProcessors": {},
"description": "使用 Ideogram 3.0 模型，根据给定的提示和可选参数同步生成图像\n具体参数请看官方文档：https://developer.ideogram.ai/api-reference/api-reference/replace-background-v3\n返回的图像 URL 在 24 小时内有效，超过该时间将无法访问图像。\n已反代图片",
"operationId": "",
"sourceUrl": "",
"method": "post",
"path": "/ideogram/v1/ideogram-v3/replace-background",
"tags": [],
"status": 1,
"requestBody": {
"type": "multipart/form-data",
"parameters": [
{
"id": "LwWFrt4lCi",
"name": "image",
"required": true,
"enable": true,
"description": "图像正在重新处理（最大大小为 10 兆字节）；目前仅支持 JPEG、WebP 和 PNG 格式。\n",
"type": "file",
"contentType": "multipart/form-data",
"schema": {
"format": "binary",
"type": "string"
},
"sampleValue": "file://C:\\Users\\Administrator\\Desktop\\例子.png"
},
{
"id": "BKjvGMvi4D",
"name": "prompt",
"required": false,
"enable": true,
"description": "",
"type": "string",
"sampleValue": "Add a forest in the background"
}
],
"jsonSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"prompt": {
"type": "string",
"description": "生成图像所需的提示文本"
},
"seed": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647,
"description": "随机种子。设置此值可获得可重复的生成结果"
},
"resolution": {
"type": "string",
"enum": [
"512x1536",
"576x1408",
"576x1472",
"576x1536",
"640x1344",
"640x1408",
"640x1472",
"640x1536",
"704x1152",
"704x1216",
"704x1280",
"704x1344",
"704x1408",
"704x1472",
"736x1312",
"768x1088",
"768x1216",
"768x1280",
"768x1344",
"800x1280",
"832x960",
"832x1024",
"832x1088",
"832x1152",
"832x1216",
"832x1248",
"864x1152",
"896x960",
"896x1024",
"896x1088",
"896x1120",
"896x1152",
"960x832",
"960x896",
"960x1024",
"960x1088",
"1024x832",
"1024x896",
"1024x960",
"1024x1024",
"1088x768",
"1088x832",
"1088x896",
"1088x960",
"1120x896",
"1152x704",
"1152x832",
"1152x864",
"1152x896",
"1216x704",
"1216x768",
"1216x832",
"1248x832",
"1280x704",
"1280x768",
"1280x800",
"1312x736",
"1344x640",
"1344x704",
"1344x768",
"1408x576",
"1408x640",
"1408x704",
"1472x576",
"1472x640",
"1472x704",
"1536x512",
"1536x576",
"1536x640"
],
"description": "支持的分辨率选项"
},
"aspect_ratio": {
"type": "string",
"enum": [
"1x3",
"3x1",
"1x2",
"2x1",
"9x16",
"16x9",
"10x16",
"16x10",
"2x3",
"3x2",
"3x4",
"4x3",
"4x5",
"5x4",
"1x1"
],
"description": "用于图像生成的纵横比，决定图像的分辨率。不能与resolution参数同时使用。默认为1x1"
},
"rendering_speed": {
"type": "string",
"enum": [
"TURBO",
"DEFAULT",
"QUALITY"
],
"default": "DEFAULT",
"description": "渲染速度选项"
},
"magic_prompt": {
"type": "string",
"enum": [
"AUTO",
"ON",
"OFF"
],
"description": "决定是否在生成请求时使用Magic Prompt"
},
"negative_prompt": {
"type": "string",
"description": "描述要在图像中排除的内容。提示中的描述优先于负面提示中的描述"
},
"num_images": {
"type": "integer",
"minimum": 1,
"maximum": 8,
"default": 1,
"description": "要生成的图像数量"
},
"color_palette": {
"description": "生成的颜色调色板，必须通过预设之一（name）或通过带有可选权重的颜色的十六进制表示（members）明确指定",
"oneOf": [
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "预设调色板名称"
}
},
"required": [
"name"
],
"additionalProperties": false,
"x-apifox-orders": [
"name"
]
},
{
"type": "object",
"properties": {
"members": {
"type": "array",
"items": {
"type": "object",
"properties": {
"color": {
"type": "string",
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "颜色的十六进制表示"
},
"weight": {
"type": "number",
"description": "颜色权重"
}
},
"required": [
"color"
],
"additionalProperties": false,
"x-apifox-orders": [
"color",
"weight"
]
}
}
},
"required": [
"members"
],
"additionalProperties": false,
"x-apifox-orders": [
"members"
]
}
],
"x-apifox-orders": [],
"properties": {}
},
"style_codes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9A-Fa-f]{8}$"
},
"description": "表示图像风格的8字符十六进制代码列表。不能与style_reference_images或style_type一起使用"
},
"style_type": {
"type": "string",
"enum": [
"AUTO",
"GENERAL",
"REALISTIC",
"DESIGN"
],
"default": "GENERAL",
"description": "要生成的风格类型"
}
},
"required": [
"prompt"
],
"dependencies": {
"resolution": {
"not": {
"required": [
"aspect_ratio"
]
}
},
"aspect_ratio": {
"not": {
"required": [
"resolution"
]
}
},
"style_codes": {
"not": {
"required": [
"style_reference_images",
"style_type"
]
}
}
},
"x-apifox-orders": [
"prompt",
"seed",
"resolution",
"aspect_ratio",
"rendering_speed",
"magic_prompt",
"negative_prompt",
"num_images",
"color_palette",
"style_codes",
"style_type"
]
},
"examples": [
{
"value": "",
"mediaType": "multipart/form-data",
"description": ""
},
{
"mediaType": "application/json",
"value": "{\r\n \"prompt\": \"voluptate reprehenderit\",\r\n \"seed\": 511526458,\r\n \"rendering_speed\": \"DEFAULT\"\r\n \r\n}",
"name": "示例 1"
}
],
"mediaType": "",
"oasExtensions": "",
"required": false,
"additionalContentTypes": []
},
"parameters": {
"path": [],
"query": [],
"cookie": [],
"header": [
{
"id": "qb8tEQbCty",
"name": "Accept",
"required": true,
"enable": true,
"description": "",
"type": "string",
"sampleValue": "application/json"
},
{
"id": "gBxcCbXhsa",
"name": "Authorization",
"required": true,
"enable": true,
"description": "",
"type": "string",
"sampleValue": "Bearer {{YOUR_API_KEY}}"
}
]
},
"commonParameters": {
"query": [],
"body": [],
"cookie": [],
"header": []
},
"auth": {
"type": "noauth"
},
"responses": [
{
"id": 116723300,
"name": "成功",
"code": 200,
"contentType": "json",
"jsonSchema": {
"type": "object",
"properties": {
"code": {
"type": "integer"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"task_id": {
"type": "string"
},
"task_status": {
"type": "string"
},
"created_at": {
"type": "integer"
},
"updated_at": {
"type": "integer"
}
},
"required": [
"task_id",
"task_status",
"created_at",
"updated_at"
],
"x-apifox-orders": [
"task_id",
"task_status",
"created_at",
"updated_at"
]
}
},
"required": [
"code",
"message",
"request_id",
"data"
],
"x-apifox-orders": [
"code",
"message",
"request_id",
"data"
]
},
"itemSchema": {},
"description": "",
"mediaType": "",
"headers": [],
"oasExtensions": ""
}
],
"responseExamples": [
{
"name": "成功示例",
"responseId": 116723300,
"data": "{\r\n \"code\": 0,\r\n \"message\": \"SUCCEED\",\r\n \"request_id\": \"CjMT7WdSwWcAAAAAALvB3g\",\r\n \"data\": {\r\n \"task_id\": \"CjMT7WdSwWcAAAAAALvB3g\",\r\n \"task_status\": \"submitted\",\r\n \"created_at\": 1733851336696,\r\n \"updated_at\": 1733851336696\r\n }\r\n}",
"description": "",
"oasKey": "",
"oasExtensions": "",
"id": "019fc09b-0b13-775e-923b-fc823eb7eb90"
}
],
"codeSamples": [],
"projectId": 8662722,
"moduleId": 8310462,
"folderId": 92436106,
"ordering": 24,
"responsibleId": 0,
"commonResponseStatus": {},
"advancedSettings": {
"disabledSystemHeaders": {},
"isDefaultUrlEncoding": 1
},
"customApiFields": {},
"oasExtensions": "",
"mockScript": {},
"createdAt": "2026-08-02T03:53:34.000Z",
"updatedAt": "2026-08-06T12:15:55.000Z",
"creatorId": 2863449,
"editorId": 2863449,
"creatorUserId": 2863449,
"editorUserId": 2863449,
"responseChildren": [],
"visibility": "INHERITED",
"securityScheme": {},
"callbacks": ""
}