lowpoly será descontinuado em 30 de out. de 2026. meshy-7 como modelo de geração 3D será descontinuado em 31 de dez. de 2026; como modelo de textura continua disponível. Troque de modelo antes dessas datas para evitar erros nas solicitações. Ver todas as descontinuações

API de Texto para imagem

Gere imagens a partir de um prompt de texto com os modelos de IA da Meshy.


POST/openapi/v1/text-to-image

Criar uma tarefa Texto para imagem

Cria uma tarefa Texto para imagem. A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa costuma levar, consulte Tempos de processamento.

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
    Obrigatório
    Description

    O modelo de IA que gera a imagem. Os preços variam de acordo com o modelo. Para preços, consulte Preços.

    Valores disponíveis:

    • nano-banana: o modelo padrão
    • nano-banana-2: mais capaz que o nano-banana
    • nano-banana-2-lite: uma versão lite do nano-banana-2
    • nano-banana-2-1: Nano Banana 2.1
    • nano-banana-pro: o modelo Pro, com qualidade superior. Requer um plano Pro ou superior. Em um plano inferior, retorna 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)
    • 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
    Obrigatório
    Description

    Texto que descreve a imagem a ser gerada. Uma descrição detalhada produz melhores resultados.

  • Name
    generate_multi_view
    Type
    boolean
    padrão false
    Description

    Se deve gerar uma imagem Multivista que mostra o assunto sob vários ângulos. Quando é true, você não pode enviar aspect_ratio. Enviar ambos retorna 400.

  • Name
    pose_mode
    Type
    string
    Description

    A pose para um personagem, a-pose ou t-pose. Deixe de fora para nenhuma pose.

    Como a pose funciona depende de ai_model:

    • nano-banana-2, nano-banana-2-lite e nano-banana-2-1: a Meshy mantém o modelo que você escolheu. A imagem é sempre 3:4, e a Meshy ignora aspect_ratio.
    • nano-banana e nano-banana-pro: a Meshy gera a imagem com nano-banana-pro, então o ai_model da tarefa retorna como nano-banana-pro. Isso requer um plano Pro ou superior. A imagem é sempre 3:4, e a Meshy ignora aspect_ratio.
    • Os modelos GPT Image (gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst, gpt-image-2-6-flare e gpt-image-2-6-sunburst): a Meshy mantém o modelo que você escolheu e o seu aspect_ratio.
  • Name
    aspect_ratio
    Type
    string
    padrão 1:1
    Description

    O formato da imagem. Os valores que você pode enviar dependem de ai_model.

    Valores disponíveis:

    • 1:1: quadrado
    • 16:9: paisagem widescreen
    • 9:16: retrato widescreen
    • 4:3: paisagem padrão
    • 3:4: retrato padrão
    • 3:2: paisagem, somente modelos GPT Image
    • 2:3: retrato, somente modelos GPT Image

    Os modelos nano-banana (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-2-1 e nano-banana-pro) retornam 400 para 3:2 e 2:3.

  • Name
    remove_background
    Type
    boolean
    padrão false
    Description

    Se deve remover o fundo da imagem. true retorna um PNG RGBA transparente, para que você possa colocar o assunto em qualquer fundo.

Retornos

O campo result da resposta contém o ID da nova tarefa Texto para imagem.

Modos de falha

  • Name
    400 - Bad Request
    Description

    A requisição não pode ser executada. A mensagem de erro informa qual problema foi encontrado. Por exemplo:

    • Parâmetro ausente: Um parâmetro obrigatório, como ai_model ou prompt, está ausente.
    • Parâmetro inválido: ai_model ou aspect_ratio não é um dos valores permitidos.
    • Conflito: aspect_ratio foi enviado com generate_multi_view: true.

    Corrija a requisição e envie-a novamente. Consulte Erros.

  • Name
    401 - Unauthorized
    Description

    A chave de API está ausente ou inválida. Verifique o cabeçalho Authorization.

  • Name
    402 - Payment Required
    Description

    A conta não pode executar esta tarefa. Por exemplo:

    • Plano gratuito: Criar uma tarefa requer um plano pago. Faça upgrade do seu plano nas configurações de assinatura e tente novamente.
    • Créditos insuficientes: A conta não tem créditos suficientes para esta tarefa (Insufficient funds), ou a conta atingiu um limite de créditos.
    • Plano necessário: A requisição usa nano-banana-pro, ou pose_mode com nano-banana, em um plano abaixo do Pro (Only Pro and above users can use nano-banana-pro, ou Only Pro and above users can use A/T pose feature (requires nano-banana-pro)).

    Verifique seu saldo de créditos e seu plano, depois tente novamente.

  • Name
    429 - Too Many Requests
    Description

    Você excedeu seu limite de taxa. Aguarde e tente novamente. Consulte Limites de taxa.


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

Get a Text to Image task

Retorna uma tarefa de Texto para imagem pelo seu 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

    O ID da tarefa da resposta de criação.

Retornos

O objeto de tarefa de Texto para imagem.


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

Excluir uma tarefa de Texto para imagem

Exclui permanentemente uma tarefa de Texto para imagem, incluindo suas imagens e dados. Você não pode desfazer uma exclusão.

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 caminho

  • Name
    id
    Type
    path
    Description

    O ID da tarefa a ser excluída.

Status da tarefa

Excluir uma tarefa PENDING reembolsa os créditos usados quando ela foi criada.

Uma tarefa IN_PROGRESS não pode ser excluída. A solicitação retorna 409 Conflict, e a tarefa continua em execução. A Meshy não reembolsa uma tarefa que já foi iniciada, então excluí-la custaria tanto os créditos quanto o resultado. Aguarde até que ela atinja o status SUCCEEDED, FAILED ou CANCELED e, então, exclua-a.

Excluir uma tarefa em um status final (SUCCEEDED, FAILED ou CANCELED) não reembolsa seus créditos.

Retornos

200 OK quando a tarefa é excluída, ou 409 Conflict quando a tarefa está IN_PROGRESS.


GET/openapi/v1/text-to-image

Listar tarefas de Texto para imagem

Retorna uma lista das suas tarefas de Texto para imagem e Imagem para imagem. O campo type de cada tarefa indica qual dos dois tipos ela é.

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

    O número da página a ser retornada. Começa em e tem como padrão 1.

  • Name
    page_size
    Type
    integer
    Description

    O número de tarefas por página, até 100. O padrão é 10.

  • Name
    sort_by
    Type
    string
    Description

    A ordem de classificação.

    Valores disponíveis:

    • +created_at: mais antigas primeiro
    • -created_at: mais recentes primeiro

Retorno

Uma lista paginada de objetos de tarefa, no mesmo formato do objeto de tarefa de Texto para imagem.


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

Transmitir uma tarefa de Texto para imagem

Transmite as atualizações de uma tarefa de Texto para imagem 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

    O ID da tarefa da resposta de criação.

Retornos

Um stream de objetos de tarefa de Texto para imagem como Server-Sent Events.

Cada evento contém o objeto de tarefa completo, no mesmo formato retornado pelo endpoint Get. Enquanto a tarefa estiver PENDING ou IN_PROGRESS, seus campos de resultado ainda não têm valores.


O objeto de tarefa Texto para imagem

Um objeto de tarefa Texto para imagem descreve uma geração de imagem a partir de um prompt de texto. Ele contém o status, o progress e as URLs da imagem quando a tarefa é bem-sucedida.

Propriedades

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

    O ID da tarefa. Trate-o como uma string opaca e não dependa do seu formato.

  • Name
    type
    Type
    string
    Description

    O tipo da tarefa, sempre text-to-image.

  • Name
    ai_model
    Type
    string
    Description

    O modelo de IA que a tarefa usou.

    Valores possíveis:

    • nano-banana
    • nano-banana-2
    • nano-banana-2-lite
    • nano-banana-2-1
    • nano-banana-pro
    • gpt-image-2
    • gpt-image-2-5-flare
    • gpt-image-2-5-sunburst
    • gpt-image-2-6-flare
    • gpt-image-2-6-sunburst
  • Name
    prompt
    Type
    string
    Description

    O prompt de texto com o qual você criou a tarefa.

  • Name
    status
    Type
    string
    Description

    O status da tarefa, um dos seguintes: PENDING, IN_PROGRESS, SUCCEEDED, FAILED ou CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Quanto da tarefa foi concluído, como porcentagem. É 0 até a tarefa começar e 100 quando ela é bem-sucedida.

  • Name
    created_at
    Type
    timestamp
    Description

    Momento em que a tarefa foi criada, em milissegundos Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Momento em que a tarefa foi iniciada, em milissegundos Unix. Ausente até a tarefa começar.

  • Name
    finished_at
    Type
    timestamp
    Description

    Momento em que a tarefa terminou, em milissegundos Unix. Ausente até a tarefa terminar.

  • Name
    expires_at
    Type
    timestamp
    Description

    Momento em que os resultados da tarefa expiram, em milissegundos Unix. Ausente até a tarefa terminar.

  • Name
    preceding_tasks
    Type
    integer
    Description

    O número de tarefas à frente desta na fila. O valor só é significativo enquanto a tarefa está PENDING. O campo é omitido quando o valor é 0.

  • Name
    image_urls
    Type
    array
    Description

    URLs de download para as imagens geradas. Com generate_multi_view: true, o array contém uma URL por visualização, geralmente três. Se o Meshy não conseguir separar todas as visualizações, ele retorna menos, e a tarefa ainda assim é bem-sucedida. Caso contrário, contém uma única URL.

  • Name
    task_error
    Type
    object
    Description

    Os detalhes do erro quando a tarefa falha. É null a menos que o status seja FAILED. Veja Erros.

  • Name
    consumed_credits
    Type
    integer
    Description

    O número de créditos que a tarefa usou. Presente quando o status é PENDING, IN_PROGRESS ou SUCCEEDED. É 0 para uma tarefa FAILED, porque o Meshy reembolsa os créditos quando uma tarefa falha.