Image to Image API

Image to Image API is a feature that allows you to integrate Meshy's AI image editing capabilities into your own application. Transform and edit existing images using reference images and text prompts with our powerful AI models.

POST/openapi/v1/image-to-image

Create an Image to Image Task

This endpoint allows you to create a new Image to Image task. Refer to The Image to Image Task Object to see which properties are included with Image to Image task object.

Parameters

  • Name
    ai_model
    Type
    string
    Required
    Description

    ID of the model to use for image generation.

    Available values:

    • nano-banana: Standard model (3 credits per image)
    • nano-banana-2: Balanced model with stronger capability than standard (6 credits per image)
    • nano-banana-pro: Pro model with enhanced quality (9 credits per image)
    • gpt-image-2: OpenAI GPT Image 2, a high-fidelity image edit model (12 credits per image)
    • gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), a high-fidelity image edit model (12 credits per image)
    • gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), a high-fidelity image edit model (12 credits per image)
  • Name
    prompt
    Type
    string
    Required
    Description

    A text description of the transformation or edit you want to apply to the reference images.

Only one of input_task_id or reference_image_urls is required. If both are provided, input_task_id takes priority.

  • Name
    input_task_id
    Type
    string
    Required
    Description

    The ID of a completed image-generation task whose output images should be used as the reference images. This task must be one of the following tasks: Text to Image or Image to Image, including their multi-view variants. In addition, it must have been run via the API and have a status of SUCCEEDED.

    All of the source task's output images are used. A single-image task contributes 1 reference image; a multi-view task contributes one per generated view, so a single task ID can fill several of the 5 reference slots.

    The source task must still be within the asset retention period — once it expires, its ID returns 404.

  • Name
    reference_image_urls
    Type
    array
    Required
    Description

    An array of 1 to 5 reference images to use for the image editing task. We currently support .jpg, .jpeg, and .png formats.

    There are two ways to provide each image:

    • Publicly accessible URL: A URL that is accessible from the public internet.
    • Data URI: A base64-encoded data URI of the image. Example of a data URI: data:image/jpeg;base64,<your base64-encoded image data>.
  • Name
    generate_multi_view
    Type
    boolean
    default false
    Description

    When set to true, generates a multi-view image showing the subject from multiple angles.

    When generate_multi_view is true, the aspect_ratio parameter cannot be set.

  • Name
    aspect_ratio
    Type
    string
    default 1:1
    Description

    Specify the aspect ratio of the output image. Allowed values depend on the selected ai_model:

    • nano-banana, nano-banana-2, nano-banana-pro: 1:1, 16:9, 9:16, 4:3, 3:4
    • gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3

    Available values:

    • 1:1: Square format
    • 16:9: Widescreen landscape
    • 9:16: Widescreen portrait
    • 4:3: Standard landscape
    • 3:4: Standard portrait
    • 3:2: Landscape (only supported by the GPT Image models)
    • 2:3: Portrait (only supported by the GPT Image models)
  • Name
    remove_background
    Type
    boolean
    default false
    Description

    When set to true, the output image is returned as a transparent RGBA PNG with the background removed, so you can composite the subject onto any background.

Returns

The result property of the response contains the task id of the newly created Image to Image task.

Failure Modes

  • Name
    400 - Bad Request
    Description

    The request was unacceptable. Common causes:

    • Missing parameter: A required parameter (e.g., ai_model, prompt) is missing, or neither reference_image_urls nor input_task_id was provided.
    • Invalid input task: The input_task_id must refer to a SUCCEEDED Text to Image or Image to Image task (multi-view included) that still has image output. A task of any other type, one that has not succeeded, or one whose images have all expired is rejected.
    • Invalid image format: One or more reference images are not supported formats.
    • Unreachable URL: One or more reference_image_urls could not be downloaded.
    • Invalid parameter: aspect_ratio is not one of the allowed values for the selected ai_model.
    • Conflict: generate_multi_view and aspect_ratio cannot be used simultaneously.
  • Name
    401 - Unauthorized
    Description

    Authentication failed. Please check your API key.

  • Name
    402 - Payment Required
    Description

    Insufficient credits to perform this task.

  • Name
    404 - Not Found
    Description

    The input_task_id does not refer to a task owned by your account. A task that does not exist and one belonging to another account return the same response.

  • Name
    429 - Too Many Requests
    Description

    You have exceeded your rate limit.

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"
}
GET/openapi/v1/image-to-image/:id

Retrieve an Image to Image Task

This endpoint allows you to retrieve an Image to Image task given a valid task id. Refer to The Image to Image Task Object to see which properties are included with Image to Image task object.

Parameters

  • Name
    id
    Type
    path
    Description

    Unique identifier for the Image to Image task to retrieve.

Returns

The response contains the Image to Image task object. Check The Image to Image Task Object section for details.

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=***"
  ]
}
DELETE/openapi/v1/image-to-image/:id

Delete an Image to Image Task

This endpoint permanently deletes an Image to Image task, including all associated images and data. This action is irreversible.

Path Parameters

  • Name
    id
    Type
    path
    Description

    The ID of the Image to Image task to delete.

Task Status

A task that is still PENDING is deleted and the credits consumed at create-time are refunded.

A task that is already IN_PROGRESS cannot be deleted: the request is rejected with 409 Conflict and the task keeps running. Credits for a task the worker has already started are not refundable, so deleting it mid-run would cost you the credits and the result both. Wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it.

A task in a terminal state (SUCCEEDED, FAILED or CANCELED) is deleted without a refund.

Returns

Returns 200 OK on success, or 409 Conflict when the task is IN_PROGRESS.

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 is left 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."
}
GET/openapi/v1/image-to-image

List Image to Image Tasks

This endpoint allows you to retrieve a list of Image to Image tasks.

Parameters

  • Name
    page_num
    Type
    integer
    Description

    Page number for pagination. Starts and defaults to 1.

  • Name
    page_size
    Type
    integer
    Description

    Page size limit. Defaults to 10 items. Maximum allowed is 100 items.

  • Name
    sort_by
    Type
    string
    Description

    Field to sort by. Available values:

    • +created_at: Sort by creation time in ascending order.
    • -created_at: Sort by creation time in descending order.

Returns

Returns a paginated list of The Image to Image Task Objects.

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=***"
    ]
  }
]
GET/openapi/v1/image-to-image/:id/stream

Stream an Image to Image Task

This endpoint streams real-time updates for an Image to Image task using Server-Sent Events (SSE).

Parameters

  • Name
    id
    Type
    path
    Description

    Unique identifier for the Image to Image task to stream.

Returns

Returns a stream of The Image to Image Task Objects as Server-Sent Events.

For PENDING or IN_PROGRESS tasks, the response stream will only include necessary progress and status fields.

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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=***"
  ]
}

The Image to Image Task Object

The Image to Image Task object is a work unit that Meshy keeps track of to generate an image from reference images and a text prompt input. The object has the following properties:

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the task. While we use a k-sortable UUID for task ids as the implementation detail, you should not make any assumptions about the format of the id.

  • Name
    type
    Type
    string
    Description

    The type of image generation task. For Image to Image tasks, this will always be image-to-image.

  • Name
    ai_model
    Type
    string
    Description

    The AI model used for this task. Possible values are nano-banana, nano-banana-2, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare, or gpt-image-2-5-sunburst.

  • Name
    prompt
    Type
    string
    Description

    The text prompt that was used to guide the image transformation.

  • Name
    status
    Type
    string
    Description

    Status of the task. Possible values are one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progress of the task. If the task is not started yet, this property will be 0. Once the task has succeeded, this will become 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp of when the task was created, in milliseconds.

    A timestamp represents the number of milliseconds elapsed since January 1, 1970 UTC, following the RFC 3339 standard. For example, Friday, September 1, 2023 12:00:00 PM GMT is represented as 1693569600000. This applies to all timestamps in Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Timestamp of when the task was started, in milliseconds. If the task is not started yet, this property will be 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Timestamp of when the task was finished, in milliseconds. If the task is not finished yet, this property will be 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Timestamp of when the task result expires, in milliseconds.

  • Name
    preceding_tasks
    Type
    integer
    Description

    The count of preceding tasks.

    The value of this field is meaningful only if the task status is PENDING.

  • Name
    image_urls
    Type
    array
    Description

    An array of downloadable URLs to the generated images. When generate_multi_view is enabled, this array contains three image URLs representing different viewing angles. Otherwise, it contains a single image URL.

  • Name
    task_error
    Type
    object
    Description

    Error details for failed tasks. See Errors for the full task_error object reference.

  • Name
    consumed_credits
    Type
    integer
    Description

    The number of credits consumed by this task. Present when the task status is PENDING, IN_PROGRESS, or SUCCEEDED. Returns 0 for FAILED tasks (credits are refunded on failure).

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
}