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.
A Imagem para imagem cria imagens. Para criar um modelo 3D do que está em uma imagem, use Imagem para 3D. Para criar um objeto que você possa segurar ou imprimir a partir de uma foto, use as APIs do Creative Lab. Elas criam uma imagem de protótipo e, em seguida, constroem um modelo 3D a partir dela, por exemplo, um chaveiro, ímã de geladeira, figura, luminária ou keycap.
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
# 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ãonano-banana-2: mais capaz que onano-banananano-banana-2-lite: uma versão lite donano-banana-2nano-banana-2-1: Nano Banana 2.1nano-banana-pro: o modelo Pro, com qualidade superior. Ele exige um plano Pro ou superior. Em um plano inferior, retorna402.gpt-image-2: OpenAI GPT Image 2gpt-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 statusSUCCEEDED.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 exemplodata:image/jpeg;base64,<your base64-encoded image data>. Um array vazio, ou mais de cinco imagens, retorna400. Se você enviar ambos, a Meshy usainput_task_id.Cada imagem precisa ser um arquivo
.jpg,.jpeg,.pngou.webpde 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 enviaraspect_ratio. Enviar ambos retorna400.
- 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: quadrado16:9: paisagem widescreen9:16: retrato widescreen4:3: paisagem padrão3:4: retrato padrão3:2: paisagem, somente para modelos GPT Image2: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-flareegpt-image-2-6-sunburst. Com um modelonano-banana,3:2e2:3retornam400.
- 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_modelouprompt, está ausente, ou nemreference_image_urlsneminput_task_idforam enviados. - Tarefa de entrada inválida:
input_task_idnão aponta para uma tarefa utilizável. Ela precisa ser uma tarefa de Texto para imagem ou Imagem para imagem com statusSUCCEEDED, 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_urlstêm mais de 20 MB. - Imagem muito pequena: Uma ou mais imagens de
reference_image_urlstêm um lado menor que 32 pixels. - Parâmetro inválido:
aspect_rationão é um dos valores que oai_modelselecionado suporta. - Conflito: A requisição envia
aspect_ratiocomgenerate_multi_view: true.
Corrija a requisição e envie-a novamente. Consulte Erros.
- Parâmetro ausente: Um parâmetro obrigatório, como
- 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-proem um plano abaixo do Pro.
Verifique seu saldo de créditos e seu plano, depois tente novamente.
- Name
404 - Not Found- Description
input_task_idnã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.
Obter uma tarefa de Imagem para imagem
Retorna uma tarefa de Imagem para imagem pelo seu ID.
Request
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
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
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.
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
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.
Stream an Image to Image task
Transmite as atualizações de uma tarefa de Imagem para imagem como Server-Sent Events (SSE).
Request
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-banananano-banana-2nano-banana-2-litenano-banana-2-1nano-banana-progpt-image-2gpt-image-2-5-flaregpt-image-2-5-sunburstgpt-image-2-6-flaregpt-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,FAILEDouCANCELED.
- Name
- progress
- Type
- integer
- Description
O quanto da tarefa foi concluído, em porcentagem. É
0até a tarefa começar e100quando é 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. É
nulla menos que o status sejaFAILED. Veja Erros.
- Name
- consumed_credits
- Type
- integer
- Description
O número de créditos que a tarefa utilizou. Presente quando o status é
PENDING,IN_PROGRESSouSUCCEEDED. É0para uma tarefaFAILED, pois o Meshy reembolsa os créditos quando uma tarefa falha.