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 Imagem para imagem

Edite e transforme imagens em sua própria aplicação. Envie imagens de referência e um prompt de texto, e os modelos de IA da Meshy geram uma nova imagem a partir deles.


POST/openapi/v1/image-to-image

Create an Image to Image task

Cria uma tarefa de Imagem para imagem. A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa costuma levar, consulte Processing times.

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

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. 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. Ele exige 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 edição ou transformação a ser aplicada às imagens de referência.

  • Name
    input_task_id
    Type
    string
    Obrigatório
    Description

    Obrigatório, a menos que você envie reference_image_urls. O ID de uma tarefa de Texto para imagem ou Imagem para imagem cujas imagens serão usadas como referências, incluindo tarefas multivista. A tarefa precisa ser uma que você criou com a API e que tenha o status SUCCEEDED.

    A Meshy usa todas as imagens que a tarefa produziu. Uma tarefa de imagem única fornece uma imagem de referência, e uma tarefa multivista fornece uma por vista. Assim, um único ID de tarefa pode preencher vários dos cinco slots de referência.

    A tarefa ainda precisa estar dentro do período de retenção de recursos. Depois que ele expira, o ID dela retorna 404.

  • Name
    reference_image_urls
    Type
    array
    Obrigatório
    Description

    Obrigatório, a menos que você envie input_task_id. De uma a cinco imagens de referência a editar, cada uma uma URL pública ou um Data URI, por exemplo data:image/jpeg;base64,<your base64-encoded image data>. Um array vazio, ou mais de cinco imagens, retorna 400. Se você enviar ambos, a Meshy usa input_task_id.

    Cada imagem precisa ser um arquivo .jpg, .jpeg, .png ou .webp de no máximo 20 MB, e com pelo menos 32 pixels em cada lado.

  • Name
    generate_multi_view
    Type
    boolean
    padrão false
    Description

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

  • Name
    aspect_ratio
    Type
    string
    padrão 1:1
    Description

    A proporção da imagem de saída. Os valores que você pode enviar dependem do 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 para modelos GPT Image
    • 2:3: retrato, somente para modelos GPT Image

    Os modelos GPT Image são gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst, gpt-image-2-6-flare e gpt-image-2-6-sunburst. Com um modelo nano-banana, 3:2 e 2:3 retornam 400.

  • Name
    remove_background
    Type
    boolean
    padrão false
    Description

    Se deve remover o fundo. Quando true, a Meshy retorna a imagem de saída como 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 de Imagem 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, ou nem reference_image_urls nem input_task_id foram enviados.
    • Tarefa de entrada inválida: input_task_id não aponta para uma tarefa utilizável. Ela precisa ser uma tarefa de Texto para imagem ou Imagem para imagem com status SUCCEEDED, incluindo multivista, que ainda tenha saída de imagem. A Meshy rejeita uma tarefa de outro tipo, uma tarefa que não foi bem-sucedida e uma tarefa cujas imagens expiraram todas.
    • Formato de imagem inválido: Uma ou mais imagens de referência não estão em um formato compatível.
    • URL inacessível: A Meshy não consegue baixar uma ou mais imagens de reference_image_urls.
    • Imagem muito grande: Uma ou mais imagens de reference_image_urls têm mais de 20 MB.
    • Imagem muito pequena: Uma ou mais imagens de reference_image_urls têm um lado menor que 32 pixels.
    • Parâmetro inválido: aspect_ratio não é um dos valores que o ai_model selecionado suporta.
    • Conflito: A requisição envia aspect_ratio 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 exige 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, ou a conta atingiu um limite de créditos.
    • Plano necessário: A requisição usa nano-banana-pro em um plano abaixo do Pro.

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

  • Name
    404 - Not Found
    Description

    input_task_id não corresponde a nenhuma tarefa em sua conta. Uma tarefa que não existe e uma tarefa que pertence a outra conta retornam a mesma resposta. Verifique o ID.

  • Name
    429 - Too Many Requests
    Description

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


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

Obter uma tarefa de Imagem para imagem

Retorna uma tarefa de Imagem para imagem pelo seu ID.

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

Parâmetros

  • Name
    id
    Type
    path
    Description

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

Retornos

O objeto de tarefa de Imagem para imagem.


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

Excluir uma tarefa de Imagem para imagem

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

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 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 requisiçã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/image-to-image

Listar tarefas de Imagem para imagem

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

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

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

Retornos

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


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

Stream an Image to Image task

Transmite as atualizações de uma tarefa de Imagem para imagem como Server-Sent Events (SSE).

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

Parâmetros

  • Name
    id
    Type
    path
    Description

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

Retornos

Um stream de objetos de tarefa de Imagem 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 Imagem para imagem

Um objeto de tarefa Imagem para imagem descreve uma imagem gerada a partir de imagens de referência e um prompt de texto. Ele contém o status, o progress e as imagens quando a tarefa é concluída com sucesso.

Propriedades

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,
  "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 de seu formato.

  • Name
    type
    Type
    string
    Description

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

  • Name
    ai_model
    Type
    string
    Description

    O modelo de IA que a tarefa utilizou.

    Valores disponí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 que guiou a edição.

  • Name
    status
    Type
    string
    Description

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

  • Name
    progress
    Type
    integer
    Description

    O quanto da tarefa foi concluído, em porcentagem. É 0 até a tarefa começar e 100 quando é concluída com sucesso.

  • Name
    created_at
    Type
    timestamp
    Description

    Horário em que a tarefa foi criada, em milissegundos Unix.

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

    Horário em que a tarefa foi concluída, em milissegundos Unix. Ausente até a tarefa terminar.

  • Name
    expires_at
    Type
    timestamp
    Description

    Horário 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, 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 é concluída com sucesso. 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 utilizou. Presente quando o status é PENDING, IN_PROGRESS ou SUCCEEDED. É 0 para uma tarefa FAILED, pois o Meshy reembolsa os créditos quando uma tarefa falha.