API de Imagem para imagem

A API de Imagem para imagem é uma funcionalidade que lhe permite integrar as capacidades de edição de imagem por IA da Meshy na sua própria aplicação. Transforme e edite imagens existentes utilizando imagens de referência e prompts de texto com os nossos poderosos modelos de IA.

Este endpoint produz imagens. Se o objetivo for um objeto que pode 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/image-to-image

Criar uma tarefa Imagem para imagem

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

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

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-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 edição de imagem de alta fidelidade (12 créditos por imagem)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), um modelo de edição de imagem de alta fidelidade (12 créditos por imagem)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), um modelo de edição de imagem de alta fidelidade (12 créditos por imagem)
Name
prompt
Type
string
Obrigatório
Description
Uma descrição textual da transformação ou edição que pretende aplicar às imagens de referência.

Apenas um de input_task_id ou reference_image_urls é obrigatório. Se ambos forem fornecidos, input_task_id tem prioridade.

Name
input_task_id
Type
string
Obrigatório
Description
O ID de uma tarefa de geração de imagem concluída cujas imagens de saída devem ser utilizadas como imagens de referência. Esta tarefa tem de ser uma das seguintes: Texto para imagem ou Imagem para imagem, incluindo as respetivas variantes multivista. Além disso, tem de ter sido executada através da API e ter o estado SUCCEEDED.
São utilizadas todas as imagens de saída da tarefa de origem. Uma tarefa de imagem única contribui com 1 imagem de referência; uma tarefa multivista contribui com uma imagem por cada vista gerada, pelo que um único ID de tarefa pode preencher várias das 5 posições de referência.
A tarefa de origem ainda tem de estar dentro do período de retenção de recursos — assim que expirar, o respetivo ID devolve 404.

Name
reference_image_urls
Type
array
Obrigatório
Description
Uma matriz de 1 a 5 imagens de referência a utilizar na tarefa de edição de imagem. Atualmente suportamos os formatos .jpg, .jpeg, .png e .webp.
Tamanho máximo do ficheiro: 20 MB por imagem.
Existem duas formas de fornecer cada imagem:
- URL acessível publicamente: Um URL acessível a partir da internet pública.
- Data URI: Um URI de dados codificado em base64 da imagem. Exemplo de um data URI: data:image/jpeg;base64,<os seus dados de imagem codificados em base64>.

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
aspect_ratio
Type
string
predefinição 1:1
Description
Especifique a proporção da imagem de saída. 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 de saída é 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 Imagem para imagem recém-criada.

Modos de Falha

Name
400 - Bad Request
Description
O pedido era inaceitável. Causas comuns:
- Parâmetro em falta: Falta um parâmetro obrigatório (por exemplo, ai_model, prompt), ou não foi fornecido nem reference_image_urls nem input_task_id.
- Tarefa de entrada inválida: O input_task_id tem de referir-se a uma tarefa SUCCEEDED de Texto para imagem ou Imagem para imagem (incluindo multivista) que ainda tenha imagens de saída disponíveis. Uma tarefa de qualquer outro tipo, uma que não tenha sido bem-sucedida, ou uma cujas imagens tenham todas expirado é rejeitada.
- Formato de imagem inválido: Uma ou mais imagens de referência não estão em formatos suportados.
- URL inacessível: Não foi possível transferir uma ou mais reference_image_urls.
- Imagem demasiado grande: Uma ou mais imagens de reference_image_urls excedem os 20 MB.
- Parâmetro inválido: aspect_ratio não é um dos valores permitidos para o ai_model selecionado.
- 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
404 - Not Found
Description
O input_task_id não se refere a uma tarefa pertencente à sua conta. Uma tarefa que não existe e uma que pertence a outra conta devolvem a mesma resposta.
Name
429 - Too Many Requests
Description
Excedeu o seu limite de taxa.

Request

POST

/openapi/v1/image-to-image

# Transform a reference image with a text prompt
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>"
    ]
  }'


 ## Using Data URI example
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "data:image/png;base64,${YOUR_BASE64_ENCODED_IMAGE_DATA}"
    ]
  }'


 ## Chaining from a previous task, instead of passing image URLs
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "input_task_id": "<your Text to Image or Image to Image task id>"
  }'

Response

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

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

Obter uma Tarefa de Imagem para imagem

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

Parâmetros

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

Retorna

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

Request

GET

/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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/image-to-image/:id

Eliminar uma Tarefa de Imagem para Imagem

Este endpoint elimina permanentemente uma tarefa de Imagem 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 Imagem 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 far-lhe-ia perder tanto os créditos como o resultado. Aguarde 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.

Devolve

Devolve 200 OK em caso de sucesso, ou 409 Conflict quando a tarefa está IN_PROGRESS.

Request

DELETE

/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-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/image-to-image

Listar tarefas de Imagem para imagem

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

Parâmetros

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

Retorna

Retorna uma lista paginada de Objetos de tarefa de Imagem para imagem.

Request

GET

/openapi/v1/image-to-image

curl https://api.meshy.ai/openapi/v1/image-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-image",
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "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/image-to-image/:id/stream

Transmitir uma tarefa de Imagem para imagem em stream

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

Parâmetros

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

Retorna

Devolve um stream de The Image to Image Task Objects como Server-Sent Events.

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

Request

GET

/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/image-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": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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=***"
  ]
}

The Image to Image Task Object

O objeto Image to Image Task é uma unidade de trabalho que a Meshy mantém sob controlo para gerar uma imagem a partir de imagens de referência e de uma entrada de prompt de texto. O objeto tem as seguintes propriedades:

Propriedades

Name
id
Type
string
Description
Identificador único da tarefa. Embora utilizemos um UUID k-sortable como detalhe de implementação para os ids das tarefas, não deve fazer nenhuma suposição sobre o formato do id.
Name
type
Type
string
Description
O tipo de tarefa de geração de imagem. Para tarefas de Image to Image, será sempre image-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 utilizado para orientar a transformação da 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 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ó tem significado 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 que representam 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. 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 Image to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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
}