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 te permite crear una nueva tarea de Texto a Imagen. Consulta El Objeto de Tarea de Texto a Imagen para ver qué propiedades están incluidas con el objeto de tarea de Texto a Imagen.

Parámetros

Name
ai_model
Type
string
Requerido
Description
ID del modelo a usar 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)
Name
prompt
Type
string
Requerido
Description
Una descripción en texto de la imagen que deseas generar. Sé descriptivo para obtener los 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 puede ser establecido.
Name
pose_mode
Type
string
Description
Especifica el pose_mode para la generación de personajes. Si se omite, la imagen se genera sin preajustes de pose.
Valores disponibles: a-pose, t-pose
Name
aspect_ratio
Type
string
predeterminado 1:1
Description
Especifica 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: 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 generada se devuelve como un PNG RGBA transparente con el fondo eliminado, para que puedas componer el sujeto sobre cualquier fondo.

Retornos

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

Modos de Falla

Name
400 - Bad Request
Description
La solicitud no fue aceptable. Causas comunes:
- Parámetro faltante: 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 pueden usarse 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/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 te 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 con el objeto de tarea de Texto a imagen.

Parámetros

Name
id
Type
path
Description
Identificador único para la tarea de Texto a imagen a recuperar.

Retornos

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.

Solicitud

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

Respuesta

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

Devuelve

Devuelve 200 OK en caso de éxito.

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

// Returns 200 Ok on success.

GET/openapi/v1/text-to-image

Listar Tareas de Texto a Imagen

Este endpoint te permite recuperar una lista de tareas de Texto 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 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 para una tarea de Texto a Imagen utilizando Server-Sent Events (SSE).

Parámetros

Name
id
Type
path
Description
Identificador único para la tarea de Texto a Imagen a transmitir.

Retornos

Devuelve un flujo de Los Objetos de la Tarea de Texto 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/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 rastrea para generar una imagen a partir de 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 ordenable por k para los ids de tarea como detalle de implementación, no debes hacer suposiciones sobre el formato del id.
Name
type
Type
string
Description
El tipo de tarea de generación de imagen. Para tareas de Texto a Imagen, esto 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, o gpt-image-2.
Name
prompt
Type
string
Description
El texto prompt 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, 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
Una matriz de URLs descargables para las imágenes generadas. Cuando generate_multi_view está habilitado, esta matriz 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 Texto a Imagen

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