Image to Image API

Edit and transform images in your own application. Send reference images and a text prompt, and Meshy's AI models generate a new image from them.

Image to Image makes images. To make a 3D model of what's in an image, use Image to 3D. To make an object you can hold or print from a photo, use the Creative Lab APIs. They make a prototype image and then build a 3D model from it, for example a keychain, fridge magnet, figure, lamp, or keycap.

POST/openapi/v1/image-to-image

Create an Image to Image task

Creates an Image to Image task. The task runs in the background. For how long a task usually takes, see Processing times.

Request

POST

/openapi/v1/image-to-image

# 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"
}

Parameters

Name
ai_model
Type
string
Required
Description
The AI model that generates the image. Prices differ by model. See Pricing.
Available values:
- nano-banana: the standard model
- nano-banana-2: more capable than nano-banana
- nano-banana-2-lite: a lite version of nano-banana-2
- nano-banana-2-1: Nano Banana 2.1
- nano-banana-pro: the Pro model, with higher quality. It needs a Pro plan or higher. On a lower plan, it returns 402.
- gpt-image-2: OpenAI GPT Image 2
- gpt-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
Required
Description
Text that describes the edit or transformation to apply to the reference images.

Name
input_task_id
Type
string
Required
Description
Required unless you send reference_image_urls. The ID of a Text to Image or Image to Image task whose images to use as the references, including multi-view tasks. The task must be one you created with the API and have the status SUCCEEDED.
Meshy uses every image the task produced. A single-image task gives one reference image, and a multi-view task gives one per view. So one task ID can fill several of the five reference slots.
The task must still be within the asset retention period. After it expires, its ID returns 404.

Name
reference_image_urls
Type
array
Required
Description
Required unless you send input_task_id. One to five reference images to edit, each a public URL or a data URI, for example data:image/jpeg;base64,<your base64-encoded image data>. An empty array, or more than five images, returns 400. If you send both, Meshy uses input_task_id.
Each image must be a .jpg, .jpeg, .png, or .webp file of at most 20 MB, and at least 32 pixels on each side.

Name
generate_multi_view
Type
boolean
default false
Description
Whether to generate a multi-view image that shows the subject from several angles. When true, you can't send aspect_ratio. Sending both returns 400.
Name
aspect_ratio
Type
string
default 1:1
Description
The aspect ratio of the output image. The values you can send depend on ai_model.
Available values:
- 1:1: square
- 16:9: widescreen landscape
- 9:16: widescreen portrait
- 4:3: standard landscape
- 3:4: standard portrait
- 3:2: landscape, GPT Image models only
- 2:3: portrait, GPT Image models only
The GPT Image models are gpt-image-2, gpt-image-2-5-flare, and gpt-image-2-5-sunburst. With a nano-banana model, 3:2 and 2:3 return 400.
Name
remove_background
Type
boolean
default false
Description
Whether to remove the background. When true, Meshy returns the output image as a transparent RGBA PNG, so you can place the subject on any background.

Returns

The result field of the response holds the ID of the new Image to Image task.

Failure modes

Name
400 - Bad Request
Description
The request can't run. The error message says which problem it found. For example:
- Missing parameter: A required parameter, such as ai_model or prompt, is missing, or neither reference_image_urls nor input_task_id was sent.
- Invalid input task: input_task_id doesn't point to a usable task. It must be a SUCCEEDED Text to Image or Image to Image task, multi-view included, that still has image output. Meshy rejects a task of another type, a task that hasn't succeeded, and a task whose images have all expired.
- Invalid image format: One or more reference images aren't in a supported format.
- Unreachable URL: Meshy can't download one or more reference_image_urls images.
- Image too large: One or more reference_image_urls images are over 20 MB.
- Image too small: One or more reference_image_urls images have a side shorter than 32 pixels.
- Invalid parameter: aspect_ratio isn't one of the values the selected ai_model supports.
- Conflict: The request sends aspect_ratio with generate_multi_view: true.
Fix the request, then send it again. See Errors.
Name
401 - Unauthorized
Description
The API key is missing or invalid. Check the Authorization header.
Name
402 - Payment Required
Description
The account can't run this task. For example:
- Free plan: Creating a task requires a paid plan. Upgrade your plan in your subscription settings, then retry.
- Insufficient credits: The account doesn't have enough credits for this task, or the account reached a credit limit.
- Plan required: The request uses nano-banana-pro on a plan below Pro.
Check your credit balance and plan, then retry.
Name
404 - Not Found
Description
input_task_id doesn't match a task in your account. A task that doesn't exist and a task that belongs to another account return the same response. Check the ID.
Name
429 - Too Many Requests
Description
You exceeded your rate limit. Wait, then retry. See Rate limits.

GET/openapi/v1/image-to-image/:id

Get an Image to Image task

Returns an Image to Image task by its ID.

Request

GET

/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

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=***"
  ]
}

Parameters

Name
id
Type
path
Description
The task ID from the create response.

Returns

The Image to Image task object.

DELETE/openapi/v1/image-to-image/:id

Delete an Image to Image task

Permanently deletes an Image to Image task, including its images and data. You can't undo a delete.

Request

DELETE

/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

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."
}

Path parameters

Name
id
Type
path
Description
The ID of the task to delete.

Task status

Deleting a PENDING task refunds the credits it used when you created it.

An IN_PROGRESS task can't be deleted. The request returns 409 Conflict, and the task keeps running. Meshy doesn't refund a task that has started, so deleting it would cost you both the credits and the result. Wait for it to reach SUCCEEDED, FAILED, or CANCELED, then delete it.

Deleting a task in a final status (SUCCEEDED, FAILED, or CANCELED) doesn't refund its credits.

Returns

200 OK when the task is deleted, or 409 Conflict when the task is IN_PROGRESS.

GET/openapi/v1/image-to-image

List Image to Image tasks

Returns a list of your Image to Image and Text to Image tasks. Each task's type field says which of the two it is.

Request

GET

/openapi/v1/image-to-image

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=***"
    ]
  }
]

Parameters

Name
page_num
Type
integer
Description
The page number to return. Starts at and defaults to 1.
Name
page_size
Type
integer
Description
The number of tasks per page, up to 100. Defaults to 10.
Name
sort_by
Type
string
Description
The sort order.
Available values:
- +created_at: oldest first
- -created_at: newest first

Returns

A paginated list of task objects, in the same format as the Image to Image task object.

GET/openapi/v1/image-to-image/:id/stream

Stream an Image to Image task

Streams an Image to Image task's updates as Server-Sent Events (SSE).

Request

GET

/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream

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=***"
  ]
}

Parameters

Name
id
Type
path
Description
The task ID from the create response.

Returns

A stream of Image to Image task objects as Server-Sent Events.

Each event holds the full task object, in the same shape the Get endpoint returns. While the task is PENDING or IN_PROGRESS, its result fields don't have values yet.

The Image to Image task object

An Image to Image task object describes one image generated from reference images and a text prompt. It holds the status, the progress, and the images when the task succeeds.

Properties

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,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ],
  "task_error": null,

  "consumed_credits": 3
}

Name
id
Type
string
Description
The task ID. Treat it as an opaque string, and don't rely on its format.
Name
type
Type
string
Description
The task type, always image-to-image.
Name
ai_model
Type
string
Description
The AI model the task used.
Available values:
- nano-banana
- nano-banana-2
- nano-banana-2-lite
- nano-banana-2-1
- nano-banana-pro
- gpt-image-2
- gpt-image-2-5-flare
- gpt-image-2-5-sunburst
Name
prompt
Type
string
Description
The text prompt that guided the edit.
Name
status
Type
string
Description
The task status, one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, or CANCELED.
Name
progress
Type
integer
Description
How much of the task is done, as a percentage. It's 0 until the task starts and 100 when it succeeds.
Name
created_at
Type
timestamp
Description
Time the task was created, in Unix milliseconds.
Name
started_at
Type
timestamp
Description
Time the task started, in Unix milliseconds. Absent until the task starts.
Name
finished_at
Type
timestamp
Description
Time the task finished, in Unix milliseconds. Absent until the task finishes.
Name
expires_at
Type
timestamp
Description
Time the task's results expire, in Unix milliseconds. Absent until the task finishes.
Name
preceding_tasks
Type
integer
Description
The number of tasks ahead of this one in the queue. The value is meaningful only while the task is PENDING. The field is left out when the value is 0.
Name
image_urls
Type
array
Description
Download URLs for the generated images. With generate_multi_view: true, it holds one URL per view, usually three. If Meshy can't separate every view, it returns fewer, and the task still succeeds. Otherwise, it holds one URL.
Name
task_error
Type
object
Description
The error details when the task fails. It's null unless the status is FAILED. See Errors.
Name
consumed_credits
Type
integer
Description
The number of credits the task used. Present when the status is PENDING, IN_PROGRESS, or SUCCEEDED. It's 0 for a FAILED task, because Meshy refunds the credits when a task fails.