API de Texto a imagen

La API de Texto a imagen es una función que te permite integrar las capacidades de generación de imágenes con IA de Meshy en tu propia aplicación. Genera imágenes de alta calidad a partir de indicaciones de texto utilizando nuestros potentes modelos de IA.

POST/openapi/v1/text-to-image

Crear una tarea de Texto a imagen

Este endpoint le permite crear una nueva tarea de Texto a imagen. Consulte El objeto de tarea de Texto a imagen para ver qué propiedades se incluyen en el objeto de tarea de Texto 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 imagen de alta fidelidad (9 créditos por imagen)
    • gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), un modelo de imagen de alta fidelidad (9 créditos por imagen)
    • gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), un modelo de imagen de alta fidelidad (9 créditos por imagen)
  • Name
    prompt
    Type
    string
    Requerido
    Description

    Una descripción textual de la imagen que desea generar. Sea descriptivo para obtener mejores resultados.

  • 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, el parámetro aspect_ratio no se puede establecer.

  • Name
    pose_mode
    Type
    string
    Description

    Especifique el pose_mode para la generación de personajes. Cuando se omite, la imagen se genera sin ningún preajuste de pose.

    Valores disponibles: a-pose, t-pose

  • Name
    aspect_ratio
    Type
    string
    predeterminado 1:1
    Description

    Especifique la relación de aspecto de la imagen generada. 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, 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 generada se devuelve como un PNG RGBA transparente con el fondo eliminado, de modo que pueda componer el sujeto sobre cualquier fondo.

Devuelve

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

Modos de fallo

  • Name
    400 - Bad Request
    Description

    La solicitud fue inaceptable. Causas comunes:

    • Falta un parámetro: Falta un parámetro requerido (por ejemplo, ai_model, prompt).
    • Parámetro inválido: ai_model o aspect_ratio no es uno de los valores permitidos.
    • Conflicto: generate_multi_view y aspect_ratio no se pueden usar simultáneamente.
  • Name
    401 - Unauthorized
    Description

    La autenticación falló. Por favor, verifique su clave de API.

  • Name
    402 - Payment Required
    Description

    Créditos insuficientes para realizar esta tarea.

  • Name
    429 - Too Many Requests
    Description

    Ha excedido su límite de tasa.

Request

POST
/openapi/v1/text-to-image
# Generate an image from a text prompt
curl https://api.meshy.ai/openapi/v1/text-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "aspect_ratio": "16:9"
  }'

Response

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

Recuperar una tarea de Texto a imagen

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

Parámetros

  • Name
    id
    Type
    path
    Description

    Identificador único de la tarea de Texto a imagen que se desea recuperar.

Devuelve

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

Request

GET
/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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/text-to-image/:id

Eliminar una tarea de Texto a imagen

Este endpoint elimina permanentemente una tarea de Texto 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 Texto 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á 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 a procesar no son reembolsables, por lo que eliminarla en mitad de la ejecución te haría perder tanto los créditos como el resultado. Espera a que alcance el estado SUCCEEDED, FAILED o CANCELED, y luego elimínala.

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á IN_PROGRESS.

Request

DELETE
/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-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/text-to-image

List Text to Image Tasks

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

Parámetros

  • Name
    page_num
    Type
    integer
    Description

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

  • Name
    page_size
    Type
    integer
    Description

    Límite de tamaño de página. Por defecto 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 Texto a imagen.

Request

GET
/openapi/v1/text-to-image
curl https://api.meshy.ai/openapi/v1/text-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-image",
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "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/text-to-image/:id/stream

Transmitir una tarea de Texto a imagen

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

Parámetros

  • Name
    id
    Type
    path
    Description

    Identificador único de la tarea de Texto a imagen que se desea transmitir.

Devuelve

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

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

Request

GET
/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v1/text-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": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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 Texto a imagen

El objeto de tarea de Texto a imagen es una unidad de trabajo que Meshy registra para generar una imagen a partir de una entrada de prompt de texto. El objeto tiene las siguientes propiedades:

Propiedades

  • Name
    id
    Type
    string
    Description

    Identificador único de la tarea. Aunque usamos un UUID k-sortable para los id de tarea como detalle de implementación, no debe asumir nada sobre el formato del id.

  • Name
    type
    Type
    string
    Description

    El tipo de tarea de generación de imagen. Para las tareas de Texto a imagen, este valor siempre será text-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, 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 generar 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, 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 ha comenzado, 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 significado si el estado de la tarea es PENDING.

  • Name
    image_urls
    Type
    array
    Description

    Un array de URL descargables a las imágenes generadas. Cuando generate_multi_view está habilitado, este array contiene tres URL 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 del error para las tareas fallidas. Consulte Errores para ver 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 las tareas FAILED (los créditos se reembolsan en caso de fallo).

Example Text to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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
}