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.
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 suele tardar una tarea, consulta Tiempos de procesamiento.
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"
}
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ándarnano-banana-2: más capaz quenano-banananano-banana-2-lite: una versión ligera denano-banana-2nano-banana-2-1: Nano Banana 2.1nano-banana-pro: el modelo Pro, con mayor calidad. Requiere un plan Pro o superior. En un plan inferior, devuelve402.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)gpt-image-2-6-flare: OpenAI GPT Image 2.6 (Flare)gpt-image-2-6-sunburst: OpenAI GPT Image 2.6 (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 referencia, incluidas las tareas multivista. La tarea debe ser una que hayas creado con la API y que tenga el estadoSUCCEEDED.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 vista. Así, un solo ID de tarea puede llenar varias de las cinco ranuras de referencia.
La tarea debe seguir dentro del período de retención de recursos. Después de que expira, 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 una URL pública o un Data URI, por ejemplodata:image/jpeg;base64,<tus datos de imagen codificados en base64>. Un array vacío, o más de cinco imágenes, devuelve400. Si envías ambos, Meshy usainput_task_id.Cada imagen debe ser un archivo
.jpg,.jpeg,.pngo.webpde un máximo de 20 MB, y de al menos 32 píxeles en cada lado.
- Name
- generate_multi_view
- Type
- boolean
- predeterminado false
- Description
Si se debe generar una imagen multivista que muestre el sujeto desde varios ángulos. Cuando es
true, no puedes enviaraspect_ratio. Enviar ambos devuelve400.
- 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: cuadrado16:9: panorámico horizontal9:16: panorámico vertical4:3: horizontal estándar3:4: vertical estándar3:2: horizontal, solo modelos GPT Image2:3: vertical, solo modelos GPT Image
Los modelos GPT Image son
gpt-image-2,gpt-image-2-5-flare,gpt-image-2-5-sunburst,gpt-image-2-6-flareygpt-image-2-6-sunburst. Con un modelonano-banana,3:2y2:3devuelven400.
- Name
- remove_background
- Type
- boolean
- predeterminado false
- Description
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 encontró. Por ejemplo:
- Falta un parámetro: Falta un parámetro requerido, como
ai_modeloprompt, o no se envió nireference_image_urlsniinput_task_id. - Tarea de entrada no válida:
input_task_idno apunta a una tarea utilizable. Debe ser una tareaSUCCEEDEDde Texto a imagen o Imagen a imagen, multivista incluida, que todavía 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_urlssuperan los 20 MB. - Imagen demasiado pequeña: Una o más imágenes de
reference_image_urlstienen un lado más corto que 32 píxeles. - Parámetro no válido:
aspect_rationo es uno de los valores que admite elai_modelseleccionado. - Conflicto: La solicitud envía
aspect_ratiocongenerate_multi_view: true.
Corrige la solicitud y vuelve a enviarla. Consulta Errores.
- Falta un parámetro: Falta un parámetro requerido, como
- Name
401 - Unauthorized- Description
Falta la clave de API o no es válida. Revisa 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-proen un plan inferior a Pro.
Verifica tu saldo de créditos y tu plan, y vuelve a intentarlo.
- Name
404 - Not Found- Description
input_task_idno coincide con ninguna tarea de tu cuenta. Una tarea que no existe y una tarea que pertenece a otra cuenta devuelven la misma respuesta. Verifica el ID.
- Name
429 - Too Many Requests- Description
Superaste tu límite de tasa. Espera y vuelve a intentarlo. Consulta Límites de tasa.
Obtener una tarea de Imagen a imagen
Devuelve una tarea de Imagen a imagen según su 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=***"
]
}
Parámetros
- Name
- id
- Type
- path
- Description
El ID de la tarea proveniente de la respuesta de creación.
Devuelve
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
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.
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
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
1y ese es el valor predeterminado.
- Name
- page_size
- Type
- integer
- Description
El número de tareas por página, hasta
100. El valor predeterminado es10.
- 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.
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
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,
"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
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-banananano-banana-2nano-banana-2-litenano-banana-2-1nano-banana-progpt-image-2gpt-image-2-5-flaregpt-image-2-5-sunburstgpt-image-2-6-flaregpt-image-2-6-sunburst
- Name
- prompt
- Type
- string
- Description
El prompt de texto que guió la edición.
- Name
- status
- Type
- string
- Description
El estado de la tarea, uno de
PENDING,IN_PROGRESS,SUCCEEDED,FAILEDoCANCELED.
- Name
- progress
- Type
- integer
- Description
Cuánto se ha completado la tarea, como porcentaje. Es
0hasta que la tarea comienza y100cuando tiene éxito.
- Name
- created_at
- Type
- timestamp
- Description
Hora en que se creó la tarea, en milisegundos Unix.
- Name
- started_at
- Type
- timestamp
- Description
Hora en que comenzó la tarea, en milisegundos Unix. Ausente hasta que la tarea comienza.
- Name
- finished_at
- Type
- timestamp
- Description
Hora en que finalizó la tarea, en milisegundos Unix. Ausente hasta que la tarea finaliza.
- Name
- expires_at
- Type
- timestamp
- Description
Hora en que expiran los resultados de la tarea, en milisegundos Unix. Ausente hasta que la tarea finaliza.
- Name
- preceding_tasks
- Type
- integer
- Description
El número de tareas por delante de esta en la cola. El valor solo es relevante mientras la tarea está en
PENDING. El campo se omite cuando el valor es0.
- Name
- image_urls
- Type
- array
- Description
URLs de descarga de las imágenes generadas. Con
generate_multi_view: true, contiene una URL por vista, normalmente tres. Si Meshy no puede separar cada vista, 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. Es
nulla menos que el estado seaFAILED. 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_PROGRESSoSUCCEEDED. Es0para una tareaFAILED, porque Meshy reembolsa los créditos cuando una tarea falla.