API de Texto para Imagem

A API de Texto para Imagem é uma funcionalidade que permite integrar as capacidades de geração de imagens por IA da Meshy na sua própria aplicação. Gere imagens de alta qualidade a partir de sugestões de texto usando os nossos poderosos modelos de IA.

POST/openapi/v1/text-to-image

Criar uma Tarefa de Texto para Imagem

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

Parâmetros

Name
ai_model
Type
string
Obrigatório
Description
ID do modelo a utilizar 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-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)
Name
prompt
Type
string
Obrigatório
Description
Uma descrição textual da imagem que deseja gerar. Seja descritivo para obter melhores resultados.
Name
generate_multi_view
Type
boolean
predefinição false
Description
Quando definido como true, gera uma imagem multivista mostrando o sujeito de múltiplos ângulos.
Quando generate_multi_view é true, o parâmetro aspect_ratio não pode ser definido.
Name
pose_mode
Type
string
Description
Especificar o mode de pose para a geração de personagens. Quando omitido, a imagem é gerada sem qualquer predefinição de pose.
Valores disponíveis: a-pose, t-pose
Name
aspect_ratio
Type
string
predefinição 1:1
Description
Especificar a proporção da imagem gerada. Os valores permitidos dependem do ai_model selecionado:
- 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 disponíveis:
- 1:1: Formato quadrado
- 16:9: Paisagem widescreen
- 9:16: Retrato widescreen
- 4:3: Paisagem padrão (não suportado por gpt-image-2)
- 3:4: Retrato padrão (não suportado por gpt-image-2)
- 3:2: Paisagem (apenas suportado por gpt-image-2)
- 2:3: Retrato (apenas suportado por gpt-image-2)
Name
remove_background
Type
boolean
predefinição false
Description
Quando definido como true, a imagem gerada é retornada como um PNG RGBA transparente com o fundo removido, para que possa compor o sujeito em qualquer fundo.

Retornos

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

Modos de Falha

Name
400 - Bad Request
Description
O pedido foi inaceitável. Causas comuns:
- Parâmetro em falta: Um parâmetro necessá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 simultaneamente.
Name
401 - Unauthorized
Description
A autenticação falhou. Por favor, verifique a sua chave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarefa.
Name
429 - Too Many Requests
Description
Excedeu o seu limite de taxa.

Pedido

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

Resposta

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

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

Recuperar uma Tarefa de Texto para Imagem

Este endpoint permite-lhe recuperar uma tarefa de Texto para Imagem dado um id de tarefa válido. Consulte O Objeto de Tarefa de Texto para Imagem para ver quais propriedades estão incluídas no objeto de tarefa de Texto para Imagem.

Parâmetros

Name
id
Type
path
Description
Identificador único para a tarefa de Texto para Imagem a recuperar.

Retorna

A resposta contém o objeto de tarefa de Texto para Imagem. Verifique a secção O Objeto de Tarefa de Texto para Imagem para detalhes.

Pedido

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

Resposta

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

Retornos

Retorna 200 OK em caso de sucesso.

Pedido

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

Resposta

// Returns 200 Ok on success.

GET/openapi/v1/text-to-image

Listar Tarefas de Texto para Imagem

Este endpoint permite-lhe obter uma lista de tarefas de Texto para Imagem.

Parâmetros

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

Retornos

Retorna uma lista paginada de Os 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 usando Server-Sent Events (SSE).

Parâmetros

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

Retornos

Retorna um fluxo de Os Objetos da Tarefa de Texto para Imagem como Server-Sent Events.

Para tarefas PENDING ou IN_PROGRESS, o fluxo de resposta incluirá apenas os campos necessários progress e 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=***"
  ]
}

O Objeto Tarefa de Texto para Imagem

O objeto Tarefa de Texto para Imagem é uma unidade de trabalho que a Meshy acompanha para gerar uma imagem a partir de uma entrada de prompt de texto. O objeto tem as seguintes propriedades:

Propriedades

Name
id
Type
string
Description
Identificador único para a tarefa. Embora utilizemos um UUID ordenável por k para os ids das tarefas como detalhe de implementação, não deve fazer quaisquer suposições sobre o formato do id.
Name
type
Type
string
Description
O tipo de tarefa de geração de imagem. Para tarefas de Texto para Imagem, isto será sempre text-to-image.
Name
ai_model
Type
string
Description
O modelo de IA utilizado para esta tarefa. Os valores possíveis são nano-banana, nano-banana-2, nano-banana-pro ou gpt-image-2.
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. Uma vez que a tarefa tenha sido concluída com sucesso, isto tornar-se-á 100.
Name
created_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi criada, em milissegundos.
Um carimbo de data/hora representa o número de milissegundos decorridos desde 1 de janeiro de 1970 UTC, seguindo o padrão RFC 3339. Por exemplo, sexta-feira, 1 de setembro de 2023, 12:00:00 PM 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 de quando a tarefa foi iniciada, 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 de quando a tarefa foi concluída, em milissegundos. Se a tarefa ainda não tiver sido concluída, 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 é significativo apenas se o estado da tarefa for PENDING.
Name
image_urls
Type
array
Description
Uma matriz de URLs descarregáveis para as imagens geradas. Quando generate_multi_view está ativado, esta matriz 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 do erro para tarefas falhadas. Veja 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. Retorna 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).

Exemplo de Objeto Tarefa de Texto para Imagem

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