影像生成影像 API
在您自己的应用程序中编辑和转换图像。发送参考图像和文本 prompt，Meshy 的 AI 模型将据此生成一张新图像。
影像生成影像用于生成图像。如果要根据图像制作 3D 模型，请使用 Image to 3D。如果要根据照片制作可以手持或打印的实物，请使用 Creative Lab APIs。它们会先生成一张原型图像，然后基于该图像构建 3D 模型，例如 Keychain、冰箱贴、Figure、灯具或 keycap。
创建一个影像生成影像任务
创建一个影像生成影像任务。该任务在后台运行。关于任务通常需要多长时间，请参阅处理时间。
Request
# Transform a reference image with a text prompt
curl https://api.meshy.ai/openapi/v1/image-to-image \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"reference_image_urls": [
"<your publicly accessible image url or base64-encoded data URI>"
]
}'
## Using data URI example
curl https://api.meshy.ai/openapi/v1/image-to-image \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"reference_image_urls": [
"data:image/png;base64,${YOUR_BASE64_ENCODED_IMAGE_DATA}"
]
}'
## Chaining from a previous task, instead of passing image URLs
curl https://api.meshy.ai/openapi/v1/image-to-image \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"input_task_id": "<your Text to Image or Image to Image task id>"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
参数
- Name
- ai_model
- Type
- string
- 必选
- Description
生成图像的 AI 模型。不同模型的价格不同。请参阅 Pricing。
可用值：
nano-banana：标准模型nano-banana-2：比nano-banana更强大nano-banana-2-lite：nano-banana-2的轻量版本nano-banana-pro：Pro 模型，质量更高。它需要 Pro 及以上的 plan。在更低的 plan 上使用会返回402。gpt-image-2：OpenAI GPT Image 2gpt-image-2-5-flare：OpenAI GPT Image 2.5（Flare）gpt-image-2-5-sunburst：OpenAI GPT Image 2.5（Sunburst）
- Name
- prompt
- Type
- string
- 必选
- Description
描述要对参考图像应用的编辑或转换的文本。
- Name
- input_task_id
- Type
- string
- 必选
- Description
除非你发送
reference_image_urls，否则此项为必填。该 ID 指向一个文字生成影像或影像生成影像任务，其生成的图像将被用作参考图像，包括多视图任务。该任务必须是你通过 API 创建、且状态为SUCCEEDED的任务。Meshy 会使用该任务生成的每一张图像。单图像任务提供一张参考图像，而多视图任务则为每个视角提供一张。因此，一个任务 ID 就可以填满五个参考图像槽位中的多个。
该任务必须仍处于资产保留期内。超过保留期后，其 ID 将返回
404。
- Name
- reference_image_urls
- Type
- array
- 必选
- Description
除非你发送
input_task_id，否则此项为必填。一到五张待编辑的参考图像，每张可以是公开可访问的 URL 或 Data URI，例如data:image/jpeg;base64,<your base64-encoded image data>。空数组或超过五张图像会返回400。如果两者都发送，Meshy 会使用input_task_id。每张图像必须是
.jpg、.jpeg、.png或.webp文件，大小不超过 20 MB，且尺寸至少为 32 × 32 像素。
- Name
- generate_multi_view
- Type
- boolean
- 默认值 false
- Description
是否生成展示主体多个角度的多视图图像。当为
true时，不能发送aspect_ratio。同时发送两者会返回400。
- Name
- aspect_ratio
- Type
- string
- 默认值 1:1
- Description
输出图像的宽高比。可发送的值取决于
ai_model。可用值：
1:1：正方形16:9：宽屏横向9:16：宽屏纵向4:3：标准横向3:4：标准纵向3:2：横向，仅限 GPT Image 模型2:3：纵向，仅限 GPT Image 模型
GPT Image 模型包括
gpt-image-2、gpt-image-2-5-flare和gpt-image-2-5-sunburst。使用nano-banana模型时，3:2和2:3会返回400。
- Name
- remove_background
- Type
- boolean
- 默认值 false
- Description
是否移除背景。当为
true时，Meshy 会以透明 RGBA PNG 格式返回输出图像，以便你将主体放置在任何背景上。
返回值
响应中的 result 字段保存了新的影像生成影像任务的 ID。
失败情况
- Name
400 - Bad Request- Description
该请求无法运行。错误消息会说明发现了什么问题。例如：
- 缺少参数：缺少必填参数，例如
ai_model或prompt，或者既未发送reference_image_urls也未发送input_task_id。 - 输入任务无效：
input_task_id未指向可用的任务。它必须是一个状态为SUCCEEDED的文字生成影像或影像生成影像任务（包括多视图），且仍有图像输出。Meshy 会拒绝其他类型的任务、未成功的任务，以及图像已全部过期的任务。 - 图像格式无效：一张或多张参考图像的格式不受支持。
- URL 无法访问：Meshy 无法下载一张或多张
reference_image_urls图像。 - 图像过大：一张或多张
reference_image_urls图像超过 20 MB。 - 图像过小：一张或多张
reference_image_urls图像小于 32 × 32 像素。 - 参数无效：
aspect_ratio不属于所选ai_model支持的值之一。 - 冲突：请求在发送
aspect_ratio的同时发送了generate_multi_view: true。
请修正请求后重新发送。请参阅 Errors。
- 缺少参数：缺少必填参数，例如
- Name
401 - Unauthorized- Description
API key 缺失或无效。请检查
Authorization请求头。
- Name
402 - Payment Required- Description
该账户无法运行此任务。例如：
- 免费 plan：创建任务需要付费 plan。请在你的subscription 设置中升级你的 plan，然后重试。
- 积分不足：账户没有足够的积分来运行此任务，或账户已达到积分限制。
- 需要更高 plan：该请求使用了
nano-banana-pro，但当前 plan 低于 Pro。
请检查你的积分余额和 plan，然后重试。
- Name
404 - Not Found- Description
input_task_id与你账户中的任何任务都不匹配。不存在的任务和属于其他账户的任务会返回相同的响应。请检查该 ID。
- Name
429 - Too Many Requests- Description
你超出了速率限制。请稍候后重试。请参阅速率限制。
获取影像生成影像任务
通过 ID 返回一个影像生成影像任务。
Request
curl https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-image",
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"expires_at": 1692771679037,
"image_urls": [
"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
]
}
删除一个影像生成影像任务
永久删除一个影像生成影像任务，包括其图像和数据。删除操作无法撤销。
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
"message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}
路径参数
- Name
- id
- Type
- path
- Description
要删除的任务的 ID。
任务状态
删除一个 PENDING 任务会退还创建该任务时所使用的积分。
IN_PROGRESS 的任务无法被删除。该请求会返回 409 Conflict，
并且任务会继续运行。Meshy 不会为已经开始的任务退款，
因此删除它会让你同时失去积分和结果。请等待它
达到 SUCCEEDED、FAILED 或 CANCELED 状态，然后再删除它。
删除处于最终状态（SUCCEEDED、FAILED 或 CANCELED）的任务
不会退还其积分。
返回值
任务被删除时返回 200 OK，当任务为
IN_PROGRESS 时返回 409 Conflict。
列出影像生成影像任务
返回你的影像生成影像和文字生成影像任务列表。每个任务的 type 字段会说明它属于这两者中的哪一种。
Request
curl https://api.meshy.ai/openapi/v1/image-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-image",
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"expires_at": 1692771679037,
"image_urls": [
"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
]
}
]
参数
- Name
- page_num
- Type
- integer
- Description
要返回的页码。起始值和默认值均为
1。
- Name
- page_size
- Type
- integer
- Description
每页的任务数量，最多为
100。默认为10。
- Name
- sort_by
- Type
- string
- Description
排序方式。
可选值：
+created_at：最旧的排在最前-created_at：最新的排在最前
返回值
一个分页的任务对象列表，格式与影像生成影像任务对象相同。
流式获取 Image to Image 任务
以服务器发送事件（SSE）的形式流式传输 Image to Image 任务的更新。
Request
curl -N https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response Stream
// Error event example
event: error
data: {
"status_code": 404,
"message": "Task not found"
}
// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-image",
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"expires_at": 1692771679037,
"image_urls": [
"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
]
}
参数
- Name
- id
- Type
- path
- Description
创建响应中返回的任务 ID。
返回
以服务器发送事件形式返回的 Image to Image 任务对象 流。
每个事件都包含完整的任务对象，其结构与 Get endpoint 返回的相同。当任务处于 PENDING 或 IN_PROGRESS 状态时，其结果字段尚无值。
Image to Image 任务对象
Image to Image 任务对象描述一个由参考图片和文本 prompt 生成的图像。它保存着状态、progress，以及任务成功后的图像。
属性
Example Image to Image Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-image",
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"expires_at": 1692771679037,
"preceding_tasks": 0,
"image_urls": [
"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
],
"task_error": {
"message": ""
},
"consumed_credits": 3
}
- Name
- id
- Type
- string
- Description
任务 ID。请将其视为一个不透明的字符串，不要依赖其格式。
- Name
- type
- Type
- string
- Description
任务类型，始终为
image-to-image。
- Name
- ai_model
- Type
- string
- Description
任务所使用的 AI 模型。
可选值：
nano-banananano-banana-2nano-banana-2-litenano-banana-progpt-image-2gpt-image-2-5-flaregpt-image-2-5-sunburst
- Name
- prompt
- Type
- string
- Description
指导此次编辑的文本 prompt。
- Name
- status
- Type
- string
- Description
任务状态，为
PENDING、IN_PROGRESS、SUCCEEDED、FAILED或CANCELED之一。
- Name
- progress
- Type
- integer
- Description
任务完成的百分比。在任务开始前为
0，成功后为100。
- Name
- created_at
- Type
- timestamp
- Description
任务创建的时间，以 Unix 毫秒表示。
- Name
- started_at
- Type
- timestamp
- Description
任务开始的时间，以 Unix 毫秒表示。在任务开始前为
0。
- Name
- finished_at
- Type
- timestamp
- Description
任务完成的时间，以 Unix 毫秒表示。在任务完成前为
0。
- Name
- expires_at
- Type
- timestamp
- Description
任务结果过期的时间，以 Unix 毫秒表示。
- Name
- preceding_tasks
- Type
- integer
- Description
排在此任务之前的队列中任务数量。该值仅在任务处于
PENDING状态时才有意义。
- Name
- image_urls
- Type
- array
- Description
生成图像的下载 URL。当
generate_multi_view: true时，每个视图对应一个 URL，通常为三个。如果 Meshy 无法分离出每个视图，则返回的数量会更少，任务仍然算作成功。否则，它只包含一个 URL。
- Name
- task_error
- Type
- object
- Description
任务失败时的错误详情。请参阅 Errors。
- Name
- consumed_credits
- Type
- integer
- Description
任务消耗的积分数量。当状态为
PENDING、IN_PROGRESS或SUCCEEDED时才存在该字段。对于FAILED的任务，该值为0，因为 Meshy 会在任务失败时退还积分。