API de Imagen a imagen

La API de Imagen a imagen es una función que te permite integrar las capacidades de edición de imágenes con IA de Meshy en tu propia aplicación. Transforma y edita imágenes existentes utilizando imágenes de referencia y mensajes de texto con nuestros potentes modelos de IA.

Este endpoint genera imágenes. Si el objetivo es un objeto que puedas sostener o imprimir —un llavero, un imán de nevera, una figura, una lámpara o una tapa de tecla a partir de una foto—, utiliza las APIs de Creative Lab (imagen de prototipo → construir modelo 3D). Si el objetivo es un modelo 3D de lo que aparece en la imagen, utiliza Imagen a 3D.

POST/openapi/v1/image-to-image

Crear una tarea de Imagen a imagen

Este endpoint le permite crear una nueva tarea de Imagen a imagen. Consulte El objeto de tarea de Imagen a imagen para ver qué propiedades se incluyen en el objeto de tarea de Imagen a imagen.

La tarea se ejecuta en segundo plano. Para saber cuánto tiempo suele tardar, consulte Tiempos de procesamiento.

Parámetros

Name
ai_model
Type
string
Requerido
Description
ID del modelo a utilizar para la generación de imágenes.
Valores disponibles:
- nano-banana: Modelo estándar (3 créditos por imagen)
- nano-banana-2: Modelo equilibrado con mayor capacidad que el estándar (6 créditos por imagen)
- nano-banana-2-lite: Variante ligera de nano-banana-2 (3 créditos por imagen)
- nano-banana-pro: Modelo Pro con calidad mejorada (9 créditos por imagen)
- gpt-image-2: OpenAI GPT Image 2, un modelo de edición de imágenes de alta fidelidad (12 créditos por imagen)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), un modelo de edición de imágenes de alta fidelidad (12 créditos por imagen)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), un modelo de edición de imágenes de alta fidelidad (12 créditos por imagen)
Name
prompt
Type
string
Requerido
Description
Una descripción textual de la transformación o edición que desea aplicar a las imágenes de referencia.

Solo se requiere uno de input_task_id o reference_image_urls. Si se proporcionan ambos, input_task_id tiene prioridad.

Name
input_task_id
Type
string
Requerido
Description
El ID de una tarea de generación de imágenes completada cuyas imágenes de salida deben usarse como imágenes de referencia. Esta tarea debe ser una de las siguientes: Texto a imagen o Imagen a imagen, incluidas sus variantes multivista. Además, debe haberse ejecutado a través de la API y tener un estado SUCCEEDED.
Se usan todas las imágenes de salida de la tarea de origen. Una tarea de una sola imagen aporta 1 imagen de referencia; una tarea multivista aporta una por cada vista generada, por lo que un único ID de tarea puede llenar varios de los 5 espacios de referencia.
La tarea de origen debe seguir estando dentro del período de retención de recursos; una vez que expira, su ID devuelve 404.

Name
reference_image_urls
Type
array
Requerido
Description
Un arreglo de entre 1 y 5 imágenes de referencia para usar en la tarea de edición de imágenes. Actualmente admitimos los formatos .jpg, .jpeg, .png y .webp.
Tamaño máximo de archivo: 20 MB por imagen.
Hay dos formas de proporcionar cada imagen:
- URL de acceso público: Una URL accesible desde internet público.
- Data URI: Un Data URI codificado en base64 de la imagen. Ejemplo de un Data URI: data:image/jpeg;base64,<your base64-encoded image data>.

Name
generate_multi_view
Type
boolean
predeterminado false
Description
Cuando se establece en true, genera una imagen multivista que muestra el sujeto desde múltiples ángulos.
Cuando generate_multi_view es true, no se puede establecer el parámetro aspect_ratio.
Name
aspect_ratio
Type
string
predeterminado 1:1
Description
Especifica la relación de aspecto de la imagen de salida. Los valores permitidos dependen del ai_model seleccionado:
- nano-banana, nano-banana-2, nano-banana-2-lite, 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
Valores disponibles:
- 1:1: Formato 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 compatible con los modelos GPT Image)
- 2:3: Vertical (solo compatible con los modelos GPT Image)
Name
remove_background
Type
boolean
predeterminado false
Description
Cuando se establece en true, la imagen de salida se devuelve como un PNG RGBA transparente con el fondo eliminado, para que pueda componer el sujeto sobre cualquier fondo.

Devuelve

La propiedad result de la respuesta contiene el id de tarea de la tarea de Imagen a imagen recién creada.

Modos de fallo

Name
400 - Bad Request
Description
La solicitud fue inaceptable. Causas comunes:
- Parámetro faltante: Falta un parámetro requerido (por ejemplo, ai_model, prompt), o no se proporcionó ni reference_image_urls ni input_task_id.
- Tarea de entrada inválida: input_task_id debe hacer referencia a una tarea SUCCEEDED de Texto a imagen o Imagen a imagen (incluida multivista) que aún tenga imágenes de salida. Se rechaza cualquier tarea de otro tipo, una que no haya tenido éxito, o una cuyas imágenes hayan expirado todas.
- Formato de imagen inválido: Una o más imágenes de referencia no están en formatos compatibles.
- URL inaccesible: No se pudieron descargar una o más reference_image_urls.
- Imagen demasiado grande: Una o más imágenes de reference_image_urls superan los 20 MB.
- Parámetro inválido: aspect_ratio no es uno de los valores permitidos para el ai_model seleccionado.
- Conflicto: generate_multi_view y aspect_ratio no se pueden usar simultáneamente.
Name
401 - Unauthorized
Description
Falló la autenticación. Verifique su clave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarea.
Name
404 - Not Found
Description
input_task_id no hace referencia a una tarea propiedad de su cuenta. Una tarea que no existe y una que pertenece a otra cuenta devuelven la misma respuesta.
Name
429 - Too Many Requests
Description
Ha excedido su límite de tasa.

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

Recuperar una tarea de Imagen a imagen

Este endpoint le permite recuperar una tarea de Imagen a imagen dado un id de tarea válido. Consulte El objeto de tarea de Imagen a imagen para ver qué propiedades se incluyen en el objeto de tarea de Imagen a imagen.

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de Imagen a imagen que se desea recuperar.

Devuelve

La respuesta contiene el objeto de tarea de Imagen a imagen. Consulte la sección El objeto de tarea de Imagen a imagen para más detalles.

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

Eliminar una tarea de Imagen a imagen

Este endpoint elimina permanentemente una tarea de Imagen a imagen, incluidas todas las imágenes y datos asociados. Esta acción es irreversible.

Parámetros de ruta

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

Estado de la tarea

Una tarea que aún está en PENDING se elimina y se reembolsan los créditos consumidos en el momento de la creación.

Una tarea que ya está en IN_PROGRESS no se puede eliminar: la solicitud se rechaza con 409 Conflict y la tarea sigue ejecutándose. Los créditos de una tarea que el worker ya ha comenzado no son reembolsables, por lo que eliminarla en medio de la ejecución le costaría tanto los créditos como el resultado. Espere a que alcance el estado SUCCEEDED, FAILED o CANCELED, y luego elimínela.

Una tarea en un estado terminal (SUCCEEDED, FAILED o CANCELED) se elimina sin reembolso.

Devuelve

Devuelve 200 OK si tiene éxito, o 409 Conflict cuando la tarea está en 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

Listar tareas de Imagen a imagen

Este endpoint le permite recuperar una lista de tareas de Imagen a imagen.

Parámetros

Name
page_num
Type
integer
Description
Número de página para la paginación. Comienza y tiene como valor predeterminado 1.
Name
page_size
Type
integer
Description
Límite de tamaño de página. El valor predeterminado es 10 elementos. El máximo permitido es 100 elementos.
Name
sort_by
Type
string
Description
Campo por el cual ordenar. Valores disponibles:
- +created_at: Ordenar por hora de creación en orden ascendente.
- -created_at: Ordenar por hora de creación en orden descendente.

Devuelve

Devuelve una lista paginada de Los objetos de tarea de Imagen a imagen.

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

Transmitir una tarea de Imagen a imagen

Este endpoint transmite actualizaciones en tiempo real para una tarea de Imagen a imagen mediante Server-Sent Events (SSE).

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de Imagen a imagen que se desea transmitir.

Devuelve

Devuelve un flujo de Los objetos de tarea de Imagen a imagen como Server-Sent Events.

Para las tareas en estado PENDING o IN_PROGRESS, el flujo de respuesta solo incluirá los campos necesarios progress y status.

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

El objeto Image to Image Task es una unidad de trabajo que Meshy rastrea para generar una imagen a partir de imágenes de referencia y un prompt de texto como entrada. El objeto tiene las siguientes propiedades:

Propiedades

Name
id
Type
string
Description
Identificador único de la tarea. Si bien usamos un UUID k-sortable para los id de tareas como detalle de implementación, no debes hacer ninguna suposición sobre el formato del id.
Name
type
Type
string
Description
El tipo de tarea de generación de imagen. Para tareas de Imagen a imagen, este valor siempre será image-to-image.
Name
ai_model
Type
string
Description
El modelo de IA utilizado para esta tarea. Los valores posibles son nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare, o gpt-image-2-5-sunburst.
Name
prompt
Type
string
Description
El prompt de texto que se utilizó para guiar la transformación de la imagen.
Name
status
Type
string
Description
Estado de la tarea. Los valores posibles son uno de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progreso de la tarea. Si la tarea aún no se ha iniciado, esta propiedad será 0. Una vez que la tarea haya tenido éxito, se convertirá en 100.
Name
created_at
Type
timestamp
Description
Marca de tiempo de cuándo se creó la tarea, en milisegundos.
Una marca de tiempo representa el número de milisegundos transcurridos desde el 1 de enero de 1970 UTC, siguiendo el estándar RFC 3339. Por ejemplo, el viernes 1 de septiembre de 2023 a las 12:00:00 PM GMT se representa como 1693569600000. Esto aplica a todas las marcas de tiempo en Meshy API.
Name
started_at
Type
timestamp
Description
Marca de tiempo de cuándo se inició la tarea, en milisegundos. Si la tarea aún no se ha iniciado, esta propiedad será 0.
Name
finished_at
Type
timestamp
Description
Marca de tiempo de cuándo finalizó la tarea, en milisegundos. Si la tarea aún no ha finalizado, esta propiedad será 0.
Name
expires_at
Type
timestamp
Description
Marca de tiempo de cuándo expira el resultado de la tarea, en milisegundos.
Name
preceding_tasks
Type
integer
Description
El recuento de tareas precedentes.
El valor de este campo solo tiene sentido si el estado de la tarea es PENDING.
Name
image_urls
Type
array
Description
Un arreglo de URLs descargables de las imágenes generadas. Cuando generate_multi_view está habilitado, este arreglo contiene tres URLs de imágenes que representan diferentes ángulos de visión. De lo contrario, contiene una única URL de imagen.
Name
task_error
Type
object
Description
Detalles del error para tareas fallidas. Consulta Errores para la referencia completa del objeto task_error.
Name
consumed_credits
Type
integer
Description
El número de créditos consumidos por esta tarea. Presente cuando el estado de la tarea es PENDING, IN_PROGRESS, o SUCCEEDED. Devuelve 0 para tareas FAILED (los créditos se reembolsan en caso de fallo).

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
}