API de Imagem para imagem

A API de Imagem para imagem é um recurso que permite integrar os recursos de edição de imagens por IA da Meshy ao seu próprio aplicativo. Transforme e edite imagens existentes usando imagens de referência e prompts de texto com nossos poderosos modelos de IA.

POST/openapi/v1/image-to-image

Criar uma tarefa de Imagem para imagem

Este endpoint permite que você crie uma nova tarefa de Imagem para imagem. Consulte O objeto da tarefa Imagem para imagem para ver quais propriedades estão incluídas no objeto da tarefa Imagem para imagem.

Parâmetros

Name
ai_model
Type
string
Obrigatório
Description
ID do modelo a ser usado para geração de imagem.
Valores disponíveis:
- nano-banana: Modelo padrão (3 créditos por imagem)
- nano-banana-2: Modelo balanceado com maior capacidade do que o padrão (6 créditos por imagem)
- nano-banana-pro: Modelo Pro com qualidade aprimorada (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)
Name
prompt
Type
string
Obrigatório
Description
Uma descrição em texto da transformação ou edição que você deseja aplicar às imagens de referência.
Name
reference_image_urls
Type
array
Obrigatório
Description
Um array de 1 a 5 imagens de referência a serem usadas para a tarefa de edição de imagem. Atualmente, oferecemos suporte aos formatos .jpg, .jpeg e .png.
Há duas maneiras de fornecer cada imagem:
- URL acessível publicamente: Uma URL acessível pela internet pública.
- Data URI: Uma Data URI da imagem codificada em base64. Exemplo de uma Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
generate_multi_view
Type
boolean
padrão false
Description
Quando definido como true, gera uma imagem Multivista mostrando o objeto a partir de vários ângulos.

Retornos

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
A solicitação era inaceitável. Causas comuns:
- Parâmetro ausente: Um parâmetro obrigatório (por exemplo, ai_model, prompt, reference_image_urls) está ausente.
- Formato de imagem inválido: Uma ou mais imagens de referência não estão em formatos compatíveis.
- URL inacessível: Não foi possível baixar uma ou mais reference_image_urls.
Name
401 - Unauthorized
Description
Falha na autenticação. Verifique sua chave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para executar esta tarefa.
Name
429 - Too Many Requests
Description
Você excedeu 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}"
    ]
  }'

Response

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

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

Recuperar uma tarefa de Imagem para imagem

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

Parâmetros

Name
id
Type
path
Description
Identificador exclusivo da tarefa de Imagem para imagem a ser recuperada.

Retorna

A resposta contém o objeto da tarefa de Imagem para imagem. Confira a seção O objeto da tarefa de Imagem para imagem para obter 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

Excluir uma tarefa de Imagem para imagem

Este endpoint exclui 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 ser excluída.

Retornos

Retorna 200 OK em caso de sucesso.

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

// Returns 200 Ok on success.

GET/openapi/v1/image-to-image

Listar tarefas de Imagem para imagem

Este endpoint permite recuperar 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 o padrão é 1.
Name
page_size
Type
integer
Description
Limite de tamanho da página. O padrão é 10 itens. O máximo permitido é 50 itens.
Name
sort_by
Type
string
Description
Campo pelo qual ordenar. Valores disponíveis:
- +created_at: Ordenar por data/hora de criação em ordem crescente.
- -created_at: Ordenar por data/hora de criação em ordem decrescente.

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 por stream

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

Parâmetros

Name
id
Type
path
Description
Identificador único da tarefa de Imagem para imagem a ser transmitida por stream.

Retornos

Retorna um stream de Objetos de tarefa de Imagem para imagem como Server-Sent Events.

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

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

O objeto de tarefa de Imagem para imagem

O objeto de tarefa de Imagem para imagem é uma unidade de trabalho que a Meshy acompanha para gerar uma imagem a partir de entradas de imagens de referência e um prompt de texto. O objeto tem as seguintes propriedades:

Propriedades

Name
id
Type
string
Description
Identificador único da tarefa. Embora usemos um UUID k-sortable para IDs de tarefa como detalhe de implementação, você 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 Imagem para imagem, isto sempre será image-to-image.
Name
ai_model
Type
string
Description
O modelo de IA usado 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 usado para orientar a transformação da imagem.
Name
status
Type
string
Description
Status da tarefa. Os valores possíveis são um de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress da tarefa. Se a tarefa ainda não foi iniciada, esta propriedade será 0. Assim que a tarefa for concluída com sucesso, isto se tornará 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. Isso se aplica 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 foi iniciada, esta propriedade será 0.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi finalizada, em milissegundos. Se a tarefa ainda não foi finalizada, 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 anteriores.
O valor deste campo só é significativo se o status da tarefa for PENDING.
Name
image_urls
Type
array
Description
Um array de URLs para download das imagens geradas. Quando generate_multi_view está habilitado, este array contém três URLs de imagem representando diferentes ângulos de visualização. Caso contrário, ele contém uma única URL de imagem.
Name
task_error
Type
object
Description
Detalhes do 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 status da tarefa é PENDING, IN_PROGRESS ou SUCCEEDED. Retorna 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
}