API de Imagen a imagen

Edita y transforma imágenes en tu propia aplicación. Envía imágenes de referencia y un prompt de texto, y los modelos de IA de Meshy generan una nueva imagen a partir de ellos.

Imagen a imagen crea imágenes. Para crear un modelo 3D de lo que aparece en una imagen, usa Imagen a 3D. Para crear un objeto que puedas sostener o imprimir a partir de una foto, usa las API de Creative Lab. Estas crean una imagen de prototipo y luego construyen un modelo 3D a partir de ella, por ejemplo un llavero, un imán de nevera, una figura, una lámpara o un keycap.

POST/openapi/v1/image-to-image

Crear una tarea de Imagen a imagen

Crea una tarea de Imagen a imagen. La tarea se ejecuta en segundo plano. Para saber cuánto tarda normalmente una tarea, consulta Tiempos de procesamiento.

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

Parámetros

Name
ai_model
Type
string
Requerido
Description
El modelo de IA que genera la imagen. Los precios varían según el modelo. Consulta Precios.
Valores disponibles:
- nano-banana: el modelo estándar
- nano-banana-2: más capaz que nano-banana
- nano-banana-2-lite: una versión ligera de nano-banana-2
- nano-banana-pro: el modelo Pro, con mayor calidad. Requiere un plan Pro o superior. En un plan inferior, devuelve 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
Requerido
Description
Texto que describe la edición o transformación que se aplicará a las imágenes de referencia.

Name
input_task_id
Type
string
Requerido
Description
Obligatorio a menos que envíes reference_image_urls. El ID de una tarea de Texto a imagen o Imagen a imagen cuyas imágenes se usarán como referencias, incluidas las tareas multivista. La tarea debe ser una que hayas creado con la API y tener el estado SUCCEEDED.
Meshy usa todas las imágenes que produjo la tarea. Una tarea de una sola imagen proporciona una imagen de referencia, y una tarea multivista proporciona una por cada vista. Por lo tanto, un solo ID de tarea puede ocupar varias de las cinco ranuras de referencia disponibles.
La tarea debe seguir dentro del período de retención de recursos. Después de que expire, su ID devuelve 404.

Name
reference_image_urls
Type
array
Requerido
Description
Obligatorio a menos que envíes input_task_id. De una a cinco imágenes de referencia para editar, cada una como URL pública o Data URI, por ejemplo data:image/jpeg;base64,<tus datos de imagen codificados en base64>. Un array vacío, o más de cinco imágenes, devuelve 400. Si envías ambos, Meshy usa input_task_id.
Cada imagen debe ser un archivo .jpg, .jpeg, .png o .webp de un máximo de 20 MB y al menos 32 × 32 píxeles.

Name
generate_multi_view
Type
boolean
predeterminado false
Description
Indica si se debe generar una imagen multivista que muestre el sujeto desde varios ángulos. Cuando es true, no puedes enviar aspect_ratio. Enviar ambos devuelve 400.
Name
aspect_ratio
Type
string
predeterminado 1:1
Description
La relación de aspecto de la imagen de salida. Los valores que puedes enviar dependen de ai_model.
Valores disponibles:
- 1:1: cuadrado
- 16:9: panorámico horizontal
- 9:16: panorámico vertical
- 4:3: horizontal estándar
- 3:4: vertical estándar
- 3:2: horizontal, solo para modelos GPT Image
- 2:3: vertical, solo para modelos GPT Image
Los modelos GPT Image son gpt-image-2, gpt-image-2-5-flare y gpt-image-2-5-sunburst. Con un modelo nano-banana, 3:2 y 2:3 devuelven 400.
Name
remove_background
Type
boolean
predeterminado false
Description
Indica si se debe eliminar el fondo. Cuando es true, Meshy devuelve la imagen de salida como un PNG RGBA transparente, para que puedas colocar el sujeto sobre cualquier fondo.

Devuelve

El campo result de la respuesta contiene el ID de la nueva tarea de Imagen a imagen.

Modos de fallo

Name
400 - Bad Request
Description
La solicitud no se puede ejecutar. El mensaje de error indica qué problema se encontró. Por ejemplo:
- Falta un parámetro: Falta un parámetro obligatorio, como ai_model o prompt, o no se envió ni reference_image_urls ni input_task_id.
- Tarea de entrada no válida: input_task_id no apunta a una tarea utilizable. Debe ser una tarea SUCCEEDED de Texto a imagen o Imagen a imagen, incluidas las multivista, que aún tenga imágenes de salida. Meshy rechaza una tarea de otro tipo, una tarea que no se completó con éxito y una tarea cuyas imágenes hayan expirado todas.
- Formato de imagen no válido: Una o más imágenes de referencia no están en un formato compatible.
- URL inaccesible: Meshy no puede descargar una o más imágenes de reference_image_urls.
- Imagen demasiado grande: Una o más imágenes de reference_image_urls superan los 20 MB.
- Imagen demasiado pequeña: Una o más imágenes de reference_image_urls son menores de 32 × 32 píxeles.
- Parámetro no válido: aspect_ratio no es uno de los valores admitidos por el ai_model seleccionado.
- Conflicto: La solicitud envía aspect_ratio junto con generate_multi_view: true.
Corrige la solicitud y vuelve a enviarla. Consulta Errores.
Name
401 - Unauthorized
Description
Falta la clave de API o no es válida. Comprueba el encabezado Authorization.
Name
402 - Payment Required
Description
La cuenta no puede ejecutar esta tarea. Por ejemplo:
- Plan gratuito: Crear una tarea requiere un plan de pago. Mejora tu plan en la configuración de suscripción y vuelve a intentarlo.
- Créditos insuficientes: La cuenta no tiene suficientes créditos para esta tarea, o la cuenta alcanzó un límite de créditos.
- Plan requerido: La solicitud usa nano-banana-pro en un plan inferior a Pro.
Comprueba tu saldo de créditos y tu plan, y vuelve a intentarlo.
Name
404 - Not Found
Description
input_task_id no coincide con ninguna tarea de tu cuenta. Una tarea inexistente y una tarea que pertenece a otra cuenta devuelven la misma respuesta. Comprueba el ID.
Name
429 - Too Many Requests
Description
Superaste tu límite de tasa. Espera y vuelve a intentarlo. Consulta Límites de tasa.

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

Obtener una tarea de Imagen a imagen

Devuelve una tarea de Imagen a imagen según su 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=***"
  ]
}

Parámetros

Name
id
Type
path
Description
El ID de la tarea proveniente de la respuesta de creación.

Devuelve

El objeto de tarea de Imagen a imagen.

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

Eliminar una tarea de Imagen a imagen

Elimina permanentemente una tarea de Imagen a imagen, incluidas sus imágenes y datos. No puedes deshacer una eliminación.

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

Parámetros de ruta

Name
id
Type
path
Description
El ID de la tarea que se va a eliminar.

Estado de la tarea

Eliminar una tarea PENDING reembolsa los créditos que utilizó al crearla.

Una tarea IN_PROGRESS no se puede eliminar. La solicitud devuelve 409 Conflict, y la tarea sigue ejecutándose. Meshy no reembolsa una tarea que ya ha comenzado, así que eliminarla te costaría tanto los créditos como el resultado. Espera a que alcance el estado SUCCEEDED, FAILED o CANCELED, y luego elimínala.

Eliminar una tarea en un estado final (SUCCEEDED, FAILED o CANCELED) no reembolsa sus créditos.

Devuelve

200 OK cuando la tarea se elimina, o 409 Conflict cuando la tarea está IN_PROGRESS.

GET/openapi/v1/image-to-image

Listar tareas de Imagen a imagen

Devuelve una lista de tus tareas de Imagen a imagen y Texto a imagen. El campo type de cada tarea indica cuál de las dos es.

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

Parámetros

Name
page_num
Type
integer
Description
El número de página a devolver. Comienza en 1 y ese es el valor predeterminado.
Name
page_size
Type
integer
Description
El número de tareas por página, hasta 100. El valor predeterminado es 10.
Name
sort_by
Type
string
Description
El orden de clasificación.
Valores disponibles:
- +created_at: las más antiguas primero
- -created_at: las más recientes primero

Devuelve

Una lista paginada de objetos de tarea, en el mismo formato que el objeto de tarea de Imagen a imagen.

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

Transmitir una tarea de Imagen a imagen

Transmite las actualizaciones de una tarea de Imagen a imagen como eventos enviados por el servidor (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=***"
  ]
}

Parámetros

Name
id
Type
path
Description
El ID de la tarea proveniente de la respuesta de creación.

Devuelve

Un flujo de objetos de tarea de Imagen a imagen como eventos enviados por el servidor.

Cada evento contiene el objeto de tarea completo, con la misma forma que devuelve el endpoint Get. Mientras la tarea esté en PENDING o IN_PROGRESS, sus campos de resultado aún no tienen valores.

El objeto de tarea de Imagen a imagen

Un objeto de tarea de Imagen a imagen describe una imagen generada a partir de imágenes de referencia y un prompt de texto. Contiene el estado, el progress y las imágenes cuando la tarea tiene éxito.

Propiedades

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
El ID de la tarea. Trátelo como una cadena opaca y no dependa de su formato.
Name
type
Type
string
Description
El tipo de tarea, siempre image-to-image.
Name
ai_model
Type
string
Description
El modelo de IA que usó la tarea.
Valores disponibles:
- nano-banana
- nano-banana-2
- nano-banana-2-lite
- nano-banana-pro
- gpt-image-2
- gpt-image-2-5-flare
- gpt-image-2-5-sunburst
Name
prompt
Type
string
Description
El prompt de texto que guio la edición.
Name
status
Type
string
Description
El estado de la tarea, uno de PENDING, IN_PROGRESS, SUCCEEDED, FAILED o CANCELED.
Name
progress
Type
integer
Description
Cuánto de la tarea se ha completado, como porcentaje. Es 0 hasta que la tarea comienza y 100 cuando tiene éxito.
Name
created_at
Type
timestamp
Description
Momento en que se creó la tarea, en milisegundos Unix.
Name
started_at
Type
timestamp
Description
Momento en que comenzó la tarea, en milisegundos Unix. Es 0 hasta que la tarea comienza.
Name
finished_at
Type
timestamp
Description
Momento en que finalizó la tarea, en milisegundos Unix. Es 0 hasta que la tarea finaliza.
Name
expires_at
Type
timestamp
Description
Momento en que expiran los resultados de la tarea, en milisegundos Unix.
Name
preceding_tasks
Type
integer
Description
El número de tareas por delante de esta en la cola. El valor solo es significativo mientras la tarea está en estado PENDING.
Name
image_urls
Type
array
Description
URLs de descarga para las imágenes generadas. Con generate_multi_view: true, contiene una URL por vista, generalmente tres. Si Meshy no puede separar todas las vistas, devuelve menos, y la tarea igualmente tiene éxito. De lo contrario, contiene una sola URL.
Name
task_error
Type
object
Description
Los detalles del error cuando la tarea falla. Consulte Errores.
Name
consumed_credits
Type
integer
Description
El número de créditos que usó la tarea. Presente cuando el estado es PENDING, IN_PROGRESS o SUCCEEDED. Es 0 para una tarea FAILED, porque Meshy reembolsa los créditos cuando una tarea falla.