API de Texto para imagem

A API de Texto para imagem é uma funcionalidade que lhe 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 instruções de texto utilizando os nossos poderosos modelos de IA.

POST/openapi/v1/text-to-image

Create a Text to Image Task

Este endpoint permite-lhe criar uma nova tarefa de Texto para imagem. Consulte The Text to Image Task Object 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 imagens.

    Valores disponíveis:

    • nano-banana: Modelo padrão (3 créditos por imagem)
    • nano-banana-2: Modelo equilibrado com maior capacidade do que o 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)
    • 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 assunto 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

  • Name
    aspect_ratio
    Type
    string
    predefinição 1:1
    Description

    Especifica a proporção (aspect ratio) 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, 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: Formato widescreen horizontal
    • 9:16: Formato widescreen vertical
    • 4:3: Formato horizontal padrão
    • 3:4: Formato vertical padrão
    • 3:2: Horizontal (apenas suportado pelos modelos GPT Image)
    • 2:3: Vertical (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 assunto sobre qualquer fundo.

Retorna

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

Modos de Falha

  • Name
    400 - Bad Request
    Description

    O pedido foi inaceitável. Causas comuns:

    • Parâmetro em falta: Falta um parâmetro obrigatório (por exemplo, ai_model, prompt).
    • Parâmetro inválido: ai_model ou aspect_ratio não corresponde a um dos valores permitidos.
    • Conflito: generate_multi_view e aspect_ratio não podem ser utilizados simultaneamente.
  • Name
    401 - Unauthorized
    Description

    A autenticação falhou. 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.

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 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 da tarefa de Texto para imagem a recuperar.

Devolve

A resposta contém o objeto de tarefa de Texto para imagem. Consulte a secção O Objeto de Tarefa de 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 do Caminho

  • Name
    id
    Type
    path
    Description

    O ID da tarefa de Texto para imagem a eliminar.

Estado da Tarefa

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

Uma tarefa que já esteja 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 faria com que perdesse tanto os créditos como o resultado. Aguarde até que atinja o estado SUCCEEDED, FAILED ou CANCELED, e só depois elimine-a.

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

List Text to Image Tasks

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 paginação. Começa e assume por defeito 1.

  • Name
    page_size
    Type
    integer
    Description

    Limite do tamanho da página. O valor por defeito é 10 itens. O máximo permitido é 100 itens.

  • Name
    sort_by
    Type
    string
    Description

    Campo pelo qual ordenar. Valores disponíveis:

    • +created_at: Ordena pela hora de criação por ordem ascendente.
    • -created_at: Ordena pela hora de criação por ordem descendente.

Devolve

Devolve 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 de 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.

Devoluções

Devolve um fluxo de Objetos de Tarefa de Texto para imagem sob a forma de 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 de tarefa Text to Image

O objeto Text to Image Task é uma unidade de trabalho que a Meshy monitoriza para gerar uma imagem a partir de um prompt de texto de 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 das 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 Text to Image, 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, 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 concluída com sucesso, passará a 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 a norma RFC 3339. Por exemplo, sexta-feira, 1 de setembro de 2023, 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 de quando a tarefa foi iniciada, em milissegundos. Se a tarefa ainda não tiver sido iniciada, 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 só é significativo se o estado da tarefa for PENDING.

  • Name
    image_urls
    Type
    array
    Description

    Uma matriz de URLs transferí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 de erro para tarefas com falha. 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
}