API de Texto para imagem

A API de Texto para imagem é uma funcionalidade que lhe permite integrar as capacidades de geração de imagens com IA da Meshy na sua própria aplicação. Gere imagens de alta qualidade a partir de prompts de texto utilizando os nossos poderosos modelos de IA.

Este endpoint produz imagens. Se o objetivo for um objeto que possa segurar ou imprimir — um porta-chaves, íman de frigorífico, figura, candeeiro ou keycap a partir de uma fotografia — utilize as APIs do Creative Lab (imagem de protótipo → construir modelo 3D). Se o objetivo for um modelo 3D do que está na imagem, utilize Imagem para 3D.

POST/openapi/v1/text-to-image

Criar uma Tarefa de Texto para Imagem

Este endpoint permite criar uma nova tarefa de Texto para imagem. Consulte O Objeto de Tarefa Texto para Imagem para ver quais propriedades estão incluídas no objeto de tarefa Texto para imagem.

A tarefa é executada em segundo plano. Para saber quanto tempo normalmente demora, consulte Tempos de Processamento.

Parâmetros

Name
ai_model
Type
string
Obrigatório
Description
ID do modelo a usar para a geração de imagem.
Valores disponíveis:
- nano-banana: Modelo padrão (3 créditos por imagem)
- nano-banana-2: Modelo equilibrado com capacidade superior ao padrão (6 créditos por imagem)
- nano-banana-2-lite: Variante lite do nano-banana-2 (3 créditos por imagem)
- nano-banana-pro: Modelo Pro com qualidade melhorada (9 créditos por imagem)
- gpt-image-2: OpenAI GPT Image 2, um modelo de imagem de alta fidelidade (9 créditos por imagem)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), um modelo de imagem de alta fidelidade (9 créditos por imagem)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), um modelo de imagem de alta fidelidade (9 créditos por imagem)
Name
prompt
Type
string
Obrigatório
Description
Uma descrição textual da imagem que pretende gerar. Seja descritivo para obter os melhores resultados.
Name
generate_multi_view
Type
boolean
predefinição false
Description
Quando definido como true, gera uma imagem Multivista que mostra o motivo a partir de vários ângulos.
Quando generate_multi_view é true, o parâmetro aspect_ratio não pode ser definido.
Name
pose_mode
Type
string
Description
Especifica o mode de pose para a geração de personagens. Quando omitido, a imagem é gerada sem quaisquer predefinições de pose.
Valores disponíveis: a-pose, t-pose
Com nano-banana, nano-banana-2, nano-banana-2-lite e nano-banana-pro, definir pose_mode fixa a proporção de imagem de saída em 3:4 e qualquer aspect_ratio que envie é ignorado. nano-banana-2 e nano-banana-2-lite mantêm o modelo pedido. Com nano-banana ou nano-banana-pro, é gerada uma imagem com pose pelo nano-banana-pro (o ai_model da tarefa é devolvido como nano-banana-pro), o que requer um plano Pro ou superior. Os modelos GPT Image (gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst) mantêm o modelo e o aspect_ratio pedidos.
Name
aspect_ratio
Type
string
predefinição 1:1
Description
Especifica a proporção da imagem gerada. Os valores permitidos dependem do ai_model selecionado:
- nano-banana, nano-banana-2, nano-banana-2-lite, 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 disponíveis:
- 1:1: Formato quadrado
- 16:9: Paisagem widescreen
- 9:16: Retrato widescreen
- 4:3: Paisagem padrão
- 3:4: Retrato padrão
- 3:2: Paisagem (apenas suportado pelos modelos GPT Image)
- 2:3: Retrato (apenas suportado pelos modelos GPT Image)
Name
remove_background
Type
boolean
predefinição false
Description
Quando definido como true, a imagem gerada é devolvida como um PNG RGBA transparente com o fundo removido, para que possa compor o motivo sobre qualquer fundo.

Devolve

A propriedade result da resposta contém o id da tarefa da tarefa de Texto para imagem recém-criada.

Modos de Falha

Name
400 - Bad Request
Description
O pedido foi inaceitável. Causas comuns:
- Parâmetro em falta: Um parâmetro obrigatório (por exemplo, ai_model, prompt) está em falta.
- Parâmetro inválido: ai_model ou aspect_ratio não é um dos valores permitidos.
- Conflito: generate_multi_view e aspect_ratio não podem ser usados em simultâneo.
Name
401 - Unauthorized
Description
A autenticação falhou. Por favor, verifique a sua chave de API.
Name
402 - Payment Required
Description
Causas comuns:
- Créditos insuficientes: A sua conta não tem créditos suficientes para realizar esta tarefa (Insufficient funds).
- Plano necessário: nano-banana-pro, ou pose_mode com nano-banana, requer um plano Pro ou superior (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)).
Name
429 - Too Many Requests
Description
Excedeu o seu limite de taxa.

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

Obter uma tarefa Texto para imagem

Este endpoint permite obter uma tarefa de Texto para imagem a partir de um id de tarefa válido. Consulte O objeto de tarefa Texto para imagem para ver quais propriedades estão incluídas no objeto de tarefa Texto para imagem.

Parâmetros

Name
id
Type
path
Description
Identificador único da tarefa de Texto para imagem a obter.

Retorno

A resposta contém o objeto de tarefa Texto para imagem. Consulte a secção O objeto de tarefa Texto para imagem para mais detalhes.

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

Este endpoint elimina permanentemente uma tarefa de Texto para imagem, incluindo todas as imagens e dados associados. Esta ação é irreversível.

Parâmetros de Caminho

Name
id
Type
path
Description
O ID da tarefa de Texto para imagem a eliminar.

Estado da Tarefa

Uma tarefa que ainda está PENDING é eliminada e os créditos consumidos no momento da criação são reembolsados.

Uma tarefa que já está IN_PROGRESS não pode ser eliminada: o pedido é rejeitado com 409 Conflict e a tarefa continua em execução. Os créditos de uma tarefa que o worker já começou a processar não são reembolsáveis, pelo que eliminá-la a meio da execução custar-lhe-ia tanto os créditos como o resultado. Aguarde até que atinja o estado SUCCEEDED, FAILED ou CANCELED, e só depois a elimine.

Uma tarefa num estado terminal (SUCCEEDED, FAILED ou CANCELED) é eliminada sem reembolso.

Retorna

Retorna 200 OK em caso de sucesso, ou 409 Conflict quando a tarefa 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

Listar Tarefas de Texto para imagem

Este endpoint permite obter uma lista de tarefas de Texto para imagem.

Parâmetros

Name
page_num
Type
integer
Description
Número da página para a paginação. Começa e tem como valor predefinido 1.
Name
page_size
Type
integer
Description
Limite do tamanho da página. O valor predefinido é 10 itens. O máximo permitido é 100 itens.
Name
sort_by
Type
string
Description
Campo pelo qual ordenar. Valores disponíveis:
- +created_at: Ordenar pelo tempo de criação em ordem ascendente.
- -created_at: Ordenar pelo tempo de criação em ordem descendente.

Retorna

Retorna uma lista paginada de Objetos de Tarefa de Texto para imagem.

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

Este endpoint transmite atualizações em tempo real para uma tarefa de Texto para imagem utilizando Server-Sent Events (SSE).

Parâmetros

Name
id
Type
path
Description
Identificador único da tarefa de Texto para imagem a transmitir.

Devolve

Devolve um fluxo de Objetos de tarefa de Texto para imagem como Server-Sent Events.

Para tarefas PENDING ou IN_PROGRESS, o fluxo de resposta incluirá apenas os campos progress e status necessários.

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

O Objeto Text to Image Task

O objeto Text to Image Task é uma unidade de trabalho que a Meshy mantém sob controlo para gerar uma imagem a partir de um prompt de texto fornecido como entrada. O objeto tem as seguintes propriedades:

Propriedades

Name
id
Type
string
Description
Identificador único da tarefa. Embora utilizemos um UUID k-sortable para os ids de tarefas como detalhe de implementação, não deve fazer suposições sobre o formato do id.
Name
type
Type
string
Description
O tipo de tarefa de geração de imagem. Para tarefas de Text to Image, este será sempre text-to-image.
Name
ai_model
Type
string
Description
O modelo de IA utilizado nesta tarefa. Os valores possíveis são nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare, ou gpt-image-2-5-sunburst.
Name
prompt
Type
string
Description
O prompt de texto que foi utilizado para gerar a imagem.
Name
status
Type
string
Description
Estado da tarefa. Os valores possíveis são um de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progresso da tarefa. Se a tarefa ainda não tiver começado, esta propriedade será 0. Assim que a tarefa for bem-sucedida, passará a ser 100.
Name
created_at
Type
timestamp
Description
Carimbo de data/hora da criação da tarefa, em milissegundos.
Um carimbo de data/hora representa o número de milissegundos decorridos desde 1 de janeiro de 1970 UTC, seguindo a norma RFC 3339. Por exemplo, sexta-feira, 1 de setembro de 2023, às 12:00:00 GMT é representado como 1693569600000. Isto aplica-se a todos os carimbos de data/hora na Meshy API.
Name
started_at
Type
timestamp
Description
Carimbo de data/hora do início da tarefa, em milissegundos. Se a tarefa ainda não tiver começado, esta propriedade será 0.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora da conclusão da tarefa, em milissegundos. Se a tarefa ainda não tiver terminado, esta propriedade será 0.
Name
expires_at
Type
timestamp
Description
Carimbo de data/hora de quando o resultado da tarefa expira, em milissegundos.
Name
preceding_tasks
Type
integer
Description
A contagem de tarefas precedentes.
O valor deste campo só é relevante se o estado da tarefa for PENDING.
Name
image_urls
Type
array
Description
Um array de URLs descarregáveis para as imagens geradas. Quando generate_multi_view está ativado, este array contém três URLs de imagem representando diferentes ângulos de visualização. Caso contrário, contém um único URL de imagem.
Name
task_error
Type
object
Description
Detalhes de erro para tarefas falhadas. Consulte Erros para a referência completa do objeto task_error.
Name
consumed_credits
Type
integer
Description
O número de créditos consumidos por esta tarefa. Presente quando o estado da tarefa é PENDING, IN_PROGRESS, ou SUCCEEDED. Devolve 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).

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
}