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 usando imágenes de referencia y mensajes de texto con nuestros potentes modelos de IA.

POST/openapi/v1/image-to-image

Crear una Tarea de Imagen a Imagen

Este endpoint te permite crear una nueva tarea de Imagen a Imagen. Consulta El Objeto de Tarea de Imagen a Imagen para ver qué propiedades están incluidas en el objeto de tarea de Imagen a Imagen.

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-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)
  • Name
    prompt
    Type
    string
    Requerido
    Description

    Una descripción en texto de la transformación o edición que deseas aplicar a las imágenes de referencia.

  • Name
    reference_image_urls
    Type
    array
    Requerido
    Description

    Un array de 1 a 5 imágenes de referencia para usar en la tarea de edición de imágenes. Actualmente soportamos formatos .jpg, .jpeg y .png.

    Hay dos maneras de proporcionar cada imagen:

    • URL accesible públicamente: Una URL que es 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 mostrando el sujeto desde múltiples ángulos.

    Cuando generate_multi_view es true, el parámetro aspect_ratio no puede ser establecido.

  • 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-pro: 1:1, 16:9, 9:16, 4:3, 3:4
    • gpt-image-2: 1:1, 16:9, 9:16, 3:2, 2:3

    Valores disponibles:

    • 1:1: Formato cuadrado
    • 16:9: Paisaje panorámico
    • 9:16: Retrato panorámico
    • 4:3: Paisaje estándar (no soportado por gpt-image-2)
    • 3:4: Retrato estándar (no soportado por gpt-image-2)
    • 3:2: Paisaje (solo soportado por gpt-image-2)
    • 2:3: Retrato (solo soportado por gpt-image-2)
  • 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 puedas componer el sujeto sobre cualquier fondo.

Devuelve

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

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, reference_image_urls).
    • Formato de imagen no válido: Uno o más formatos de imágenes de referencia no son soportados.
    • URL inalcanzable: Una o más reference_image_urls no pudieron ser descargadas.
    • Parámetro no válido: aspect_ratio no es uno de los valores permitidos para el ai_model seleccionado.
    • Conflicto: generate_multi_view y aspect_ratio no pueden ser usados simultáneamente.
  • Name
    401 - Unauthorized
    Description

    La autenticación falló. Por favor, verifica tu clave de API.

  • Name
    402 - Payment Required
    Description

    Créditos insuficientes para realizar esta tarea.

  • Name
    429 - Too Many Requests
    Description

    Has excedido tu 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}"
    ]
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/v1/image-to-image/:id

Recuperar una Tarea de Imagen a Imagen

Este endpoint te permite recuperar una tarea de Imagen a Imagen dado un id de tarea válido. Consulta El Objeto de Tarea de Imagen a Imagen para ver qué propiedades están incluidas con el objeto de tarea de Imagen a Imagen.

Parámetros

  • Name
    id
    Type
    path
    Description

    Identificador único para la tarea de Imagen a Imagen a recuperar.

Devuelve

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

Solicitud

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

Respuesta

{
  "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, incluyendo 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 a eliminar.

Devuelve

Devuelve 200 OK en caso de éxito.

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

// Returns 200 Ok on success.
GET/openapi/v1/image-to-image

Listar Tareas de Imagen a Imagen

Este endpoint te permite recuperar una lista de tareas de Imagen a Imagen.

Parámetros

  • Name
    page_num
    Type
    integer
    Description

    Número de página para paginación. Comienza y por defecto es 1.

  • Name
    page_size
    Type
    integer
    Description

    Límite del tamaño de página. Por defecto es 10 elementos. El máximo permitido es 50 elementos.

  • Name
    sort_by
    Type
    string
    Description

    Campo para ordenar. Valores disponibles:

    • +created_at: Ordenar por tiempo de creación en orden ascendente.
    • -created_at: Ordenar por tiempo de creación en orden descendente.

Retornos

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 utilizando Server-Sent Events (SSE).

Parámetros

  • Name
    id
    Type
    path
    Description

    Identificador único para la tarea de Imagen a Imagen a transmitir.

Retornos

Devuelve un flujo de Los Objetos de Tarea de Imagen a Imagen como Server-Sent Events.

Para tareas PENDING o IN_PROGRESS, el flujo de respuesta solo incluirá los campos necesarios de 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=***"
  ]
}

El Objeto de Tarea de Imagen a Imagen

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

Propiedades

  • Name
    id
    Type
    string
    Description

    Identificador único para la tarea. Aunque usamos un UUID k-sortable para los ids de tarea 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, esto 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-pro o gpt-image-2.

  • Name
    prompt
    Type
    string
    Description

    El texto prompt 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 ha comenzado, esta propiedad será 0. Una vez que la tarea haya tenido éxito, esto se convertirá en 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Marca de tiempo de cuando 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 se aplica a todas las marcas de tiempo en Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Marca de tiempo de cuando se inició la tarea, en milisegundos. Si la tarea aún no ha comenzado, esta propiedad será 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Marca de tiempo de cuando se terminó la tarea, en milisegundos. Si la tarea aún no ha terminado, esta propiedad será 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Marca de tiempo de cuando expira el resultado de la tarea, en milisegundos.

  • Name
    preceding_tasks
    Type
    integer
    Description

    El conteo de tareas precedentes.

    El valor de este campo es significativo solo si el estado de la tarea es PENDING.

  • Name
    image_urls
    Type
    array
    Description

    Un arreglo de URLs descargables para 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 sola URL de imagen.

  • Name
    task_error
    Type
    object
    Description

    Detalles de 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).

Ejemplo de Objeto de Tarea de Imagen a Imagen

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