API de Texto a imagen

Genera imágenes a partir de un prompt de texto con los modelos de IA de Meshy.

Texto a imagen crea imágenes. Para crear un modelo 3D de lo que aparece en una imagen, utiliza Imagen a 3D. Para crear un objeto que puedas sostener o imprimir a partir de una foto, utiliza 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/text-to-image

Crear una tarea de Texto a imagen

Crea una tarea de Texto a imagen. La tarea se ejecuta en segundo plano. Para saber cuánto suele tardar una tarea, consulta Tiempos de procesamiento.

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

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. Para conocer los precios, 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. Necesita 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 imagen que se va a generar. Una descripción detallada da mejores resultados.
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
pose_mode
Type
string
Description
La pose para un personaje, a-pose o t-pose. Omítelo para no usar ninguna pose.
El funcionamiento de una pose depende de ai_model:
- nano-banana-2 y nano-banana-2-lite: Meshy mantiene el modelo que elegiste. La imagen siempre es 3:4, y Meshy ignora aspect_ratio.
- nano-banana y nano-banana-pro: Meshy genera la imagen con nano-banana-pro, por lo que el ai_model de la tarea se lee como nano-banana-pro. Esto requiere un plan Pro o superior. La imagen siempre es 3:4, y Meshy ignora aspect_ratio.
- Los modelos GPT Image (gpt-image-2, gpt-image-2-5-flare y gpt-image-2-5-sunburst): Meshy mantiene el modelo que elegiste y tu aspect_ratio.
Name
aspect_ratio
Type
string
predeterminado 1:1
Description
La forma de la imagen. 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 modelos GPT Image
- 2:3: vertical, solo modelos GPT Image
Los modelos nano-banana (nano-banana, nano-banana-2, nano-banana-2-lite y nano-banana-pro) devuelven 400 para 3:2 y 2:3.
Name
remove_background
Type
boolean
predeterminado false
Description
Indica si se debe eliminar el fondo de la imagen. true devuelve un PNG RGBA transparente, para que puedas colocar el sujeto sobre cualquier fondo.

Resultados devueltos

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

Modos de fallo

Name
400 - Bad Request
Description
La solicitud no puede ejecutarse. El mensaje de error indica qué problema encontró. Por ejemplo:
- Parámetro faltante: falta un parámetro obligatorio, como ai_model o prompt.
- Parámetro inválido: ai_model o aspect_ratio no es uno de los valores permitidos.
- Conflicto: se envió aspect_ratio junto con generate_multi_view: true.
Corrige la solicitud y envíala de nuevo. Consulta Errores.
Name
401 - Unauthorized
Description
La clave de API falta 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. Actualiza tu plan en tu configuración de suscripción y vuelve a intentarlo.
- Créditos insuficientes: la cuenta no tiene créditos suficientes para esta tarea (Insufficient funds), o la cuenta alcanzó un límite de créditos.
- Plan requerido: la solicitud usa nano-banana-pro, o pose_mode con nano-banana, en un plan inferior a Pro (Only Pro and above users can use nano-banana-pro, o Only Pro and above users can use A/T pose feature (requires nano-banana-pro)).
Revisa tu saldo de créditos y tu plan, y vuelve a intentarlo.
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/text-to-image/:id

Obtener una tarea de Texto a imagen

Devuelve una tarea de Texto a imagen por su ID.

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

Parámetros

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

Devuelve

El objeto de tarea de Texto a imagen.

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

Eliminar una tarea de Texto a imagen

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

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 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ó cuando la creaste.

Una tarea IN_PROGRESS no se puede eliminar. La solicitud devuelve 409 Conflict, y la tarea sigue en ejecución. Meshy no reembolsa una tarea que ya ha comenzado, por lo 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/text-to-image

Listar tareas de Texto a imagen

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

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

Parámetros

Name
page_num
Type
integer
Description
El número de página a devolver. Comienza en 1 y este 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 Texto a imagen.

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

Transmitir una tarea de Texto a imagen

Transmite las actualizaciones de una tarea de Texto a imagen como Server-Sent Events (SSE).

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

Parámetros

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

Devuelve

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

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

El objeto de tarea Text to Image

Un objeto de tarea Text to Image describe una generación de imagen a partir de un prompt de texto. Contiene el estado, el progress y las URL de las imágenes cuando la tarea tiene éxito.

Propiedades

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
}

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 text-to-image.
Name
ai_model
Type
string
Description
El modelo de IA que usó la tarea.
Valores posibles:
- 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 con el que creó la tarea.
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 está 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á PENDING.
Name
image_urls
Type
array
Description
URL de descarga de las imágenes generadas. Con generate_multi_view: true, el array contiene una URL por vista, normalmente 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.