API de Multi-imagem para 3D
Gere um modelo 3D a partir de uma a quatro imagens do mesmo objeto, capturadas de ângulos diferentes.
Create a Multi-Image to 3D task
Cria uma tarefa de Multi-imagem para 3D. A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa costuma levar, consulte Tempos de processamento. Para os campos que uma tarefa possui, consulte O objeto de tarefa Multi-imagem para 3D.
Request
# Simple request
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_urls": [
"<your publicly accessible image url or base64-encoded data URI>",
"<your second publicly accessible image url or base64-encoded data URI>"
]
}'
# With Ultra 2K geometry, PBR texturing, and GLB format
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_urls": [
"<your publicly accessible image url or base64-encoded data URI>",
"<your second publicly accessible image url or base64-encoded data URI>"
],
"ai_model": "meshy-7.1",
"geometry_resolution": "2k",
"should_texture": true,
"enable_pbr": true,
"target_formats": ["glb"]
}'
# Textured with Meshy N1 from the input images, the first as the front view
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_urls": [
"<your front view image url or base64-encoded data URI>",
"<your back view image url or base64-encoded data URI>"
],
"ai_model": "meshy-7.1",
"texture_model": "meshy-n1"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Parâmetros
- Name
- input_task_id
- Type
- string
- Obrigatório
- Description
Obrigatório, a menos que você envie
image_urls. O ID de uma tarefa de Texto para imagem ou Imagem para imagem, incluindo uma de multivista. Meshy usa de uma a quatro imagens dessa tarefa como entrada. A tarefa deve ser uma que você criou com a API e que tenha o statusSUCCEEDED.
- Name
- image_urls
- Type
- array
- Obrigatório
- Description
Obrigatório, a menos que você envie
input_task_id. De uma a quatro imagens, cada uma como uma URL pública ou um Data URI, comodata:image/jpeg;base64,<your base64-encoded image data>. Se você enviar ambos, Meshy usainput_task_id.Cada imagem deve ser um arquivo
.jpg,.jpeg,.pngou.webpde no máximo 20 MB, com pelo menos 32 pixels em cada lado e no máximo 178.956.970 pixels (largura × altura). Mais de quatro imagens retorna400.Para obter os melhores resultados, as imagens devem mostrar o mesmo objeto sob ângulos diferentes. Com
meshy-7.1oulatest, Meshy usa a primeira imagem como a vista frontal, e a ordem das demais não importa.
- Name
- ai_model
- Type
- string
- padrão latest
- Description
O modelo de IA que gera o modelo 3D.
Valores disponíveis:
latest: Meshy 7.1meshy-7.1meshy-6meshy-6-litemeshy-7: obsoleto, enviemeshy-7.1em vez disso. Será desativado em 31 de dezembro de 2026.
Consulte Modelos para saber qual modelo se adequa ao seu projeto, como um objeto real ou uma impressão 3D.
- Name
- geometry_resolution
- Type
- string
- padrão standard
- Description
Quanto detalhe de geometria gerar.
Valores disponíveis:
standard2k: executa a passagem Ultra em 2048³. Requermeshy-7.1,latestou omeshy-7obsoleto.
- Name
- ultra_mode
- Type
- boolean
- ⚠ obsoleto
- padrão false
- Description
Envie
geometry_resolutionem vez disso.ultra_mode: trueé o mesmo quegeometry_resolution: "2k".
- Name
- should_texture
- Type
- boolean
- padrão true
- Description
Se deve gerar texturas.
trueretorna um modelo texturizado, efalsepula a etapa de textura e retorna uma malha sem texturas.
should_texture = true- Name
- texture_model
- Type
- string
- padrão depends on ai_model
- Description
O modelo de IA que texturiza o modelo 3D a partir de várias vistas, na mesma tarefa. Deixe de fora para usar o modelo de textura padrão do seu
ai_model. Isso não altera o custo em créditos.Valores disponíveis:
meshy-7: Meshy 7, com mapas PBR e texturas de até 8Kmeshy-n1: Meshy N1, uma textura de cor base em 2K apenas a partir de imagens de referência
Todo
ai_modelaceita ambos. Uma solicitação texturizada commeshy-6oumeshy-6-literetorna400, assim como uma opção que o modelo de textura escolhido não suporta. Comshould_texture: false, Meshy ignoratexture_model, mas um valor desconhecido ainda retorna400.Com
meshy-n1, Meshy texturiza a partir detexture_image_urlsoutexture_image_url, ou a partir das imagens de entrada quando você não envia nenhum dos dois. A primeira imagem é a vista frontal. Um modelo gerado com mais de 7.999.999 triângulos falha a tarefa, e Meshy reembolsa os créditos.Consulte Modelos para saber o que cada modelo de textura faz e qual escolher.
- Name
- enable_pbr
- Type
- boolean
- padrão false
- Description
Se também deve gerar mapas metálico, de rugosidade e normal, além da cor base. O modelo de textura Meshy 6 também gera um mapa de emissão, exceto em
texture_resolution: 8k. Comtexture_model: meshy-n1,trueretorna400.
- Name
- texture_resolution
- Type
- string
- padrão 2k
- Description
O tamanho da textura de cor base. Um tamanho maior captura mais detalhes de superfície.
Valores disponíveis:
2k: 2048×20484k: 4096×40968k: 8192×8192
4ke8krequerem o modelo de textura Meshy 7 ou Meshy 6, e retornam400com os demais. Em8k, Meshy não gera um mapa de emissão.
- Name
- hd_texture
- Type
- boolean
- ⚠ obsoleto
- padrão false
- Description
Envie
texture_resolutionem vez disso.hd_texture: trueé o mesmo quetexture_resolution: "4k". Se você enviar ambos, Meshy usatexture_resolution.
- Name
- texture_prompt
- Type
- string
- Description
Texto que guia a textura, com até 800 caracteres. Um texto mais longo retorna
400. Comtexture_model: meshy-n1, enviá-lo retorna400.
- Name
- texture_image_url
- Type
- string
- Description
Uma imagem 2D que guia a textura, como uma URL pública ou um Data URI, como
data:image/jpeg;base64,<your base64-encoded image data>. A imagem deve ser um arquivo.jpg,.jpeg,.pngou.webpde no máximo 20 MB, com pelo menos 32 pixels em cada lado e no máximo 178.956.970 pixels (largura × altura).Se você enviar
texture_image_urletexture_promptjuntos, Meshy usatexture_prompt. Comtexture_model: meshy-n1, Meshy texturiza a partir dessa imagem como a vista frontal.A textura pode não ficar boa quando a forma na imagem difere muito do modelo 3D.
- Name
- texture_image_urls
- Type
- string[]
- Description
De uma a quatro imagens do objeto sob vistas diferentes que guiam a textura. Meshy usa a primeira imagem como a vista frontal. A ordem das demais vistas (esquerda, traseira, direita) não importa.
Cada imagem segue as mesmas regras de
texture_image_url. É uma URL pública ou um Data URI, em formato.jpg,.jpeg,.pngou.webp, de no máximo 20 MB, com pelo menos 32 pixels em cada lado e no máximo 178.956.970 pixels (largura × altura).Essas imagens guiam apenas a textura e não dependem de
image_urls. As duas listas podem conter imagens diferentes e números diferentes de imagens.texture_image_urlsrequer o modelo de textura Meshy 7 ou Meshy N1. Envie-o com um destes:ai_modeligual ameshy-7.1,latestou omeshy-7obsoletotexture_modeligual ameshy-7oumeshy-n1
Você não pode enviá-lo com
texture_image_urloutexture_prompt.
- Name
- should_remesh
- Type
- boolean
- padrão true (meshy-6-lite), false (other models)
- Description
Se deve refazer a malha (remesh) do modelo após a geração. Para o modelo 3D de maior qualidade, defina como
false.
should_remesh = true- Name
- topology
- Type
- string
- padrão triangle
- Description
O tipo de face do modelo com remesh.
Valores disponíveis:
quad: uma malha predominantemente quadtriangle: uma malha triangular decimada
Com
texture_model: meshy-n1,quadretorna400quando o modelo passa por remesh, o quemeshy-6-litefaz por padrão.
- Name
- target_polycount
- Type
- integer
- padrão 30000
- Description
O número de faces desejado, de
100a300000. O resultado pode diferir do alvo, dependendo da geometria do modelo. Um valor fora do intervalo retorna400.
- Name
- decimation_mode
- Type
- integer
- Description
Contagem de faces adaptativa, por nível. Quando você define isso, Meshy ignora
target_polycount.Valores disponíveis:
1: ultra2: alta3: média4: baixa
- Name
- save_pre_remeshed_model
- Type
- boolean
- padrão false
- Description
Se também deve salvar o GLB de antes do remesh, retornado em
model_urls.pre_remeshed_glb.
- Name
- symmetry_mode
- Type
- string
- ⚠ obsoleto
- padrão auto
- Description
Deixe de fora. Não afeta a saída.
Valores disponíveis:
off: sem simetriaauto: simetria baseada na geometria de entradaon: simetria forçada
- Name
- pose_mode
- Type
- string
- Description
A pose para um modelo de personagem,
a-poseout-pose. Para não ter pose nenhuma, deixe de forapose_modeeis_a_t_pose.
- Name
- is_a_t_pose
- Type
- boolean
- ⚠ obsoleto
- padrão false
- Description
Envie
pose_modeem vez disso. Se deve gerar o modelo em uma pose A ou T.
- Name
- image_enhancement
- Type
- boolean
- padrão true
- Description
Se deve otimizar as imagens de entrada antes de gerar.
falsemantém o visual exato das imagens de entrada, sem processamento de estilo. Suportado apenas commeshy-6,meshy-7.1oulatest. Enviá-lo commeshy-6-literetorna400.
- Name
- remove_lighting
- Type
- boolean
- padrão true
- Description
Se deve remover realces e sombras da textura de cor base. O resultado mais limpo funciona melhor sob sua própria iluminação. Apenas o modelo de textura Meshy 6 o utiliza, e em
texture_resolution: 8kele sempre remove a iluminação. Comtexture_model: meshy-n1,trueretorna400. Comai_model: meshy-6-litee seu modelo de textura padrão, enviá-lo retorna400.
- Name
- moderation
- Type
- boolean
- padrão false
- Description
Se deve verificar as entradas em busca de conteúdo prejudicial. Meshy verifica cada imagem de entrada,
texture_image_urlou cada imagem emtexture_image_urls, e o texto emtexture_prompt. Se Meshy encontrar conteúdo prejudicial, a solicitação retorna400e Meshy não cria uma tarefa.
- Name
- target_formats
- Type
- string[]
- Description
Os formatos de arquivo 3D a gerar. Meshy gera e retorna apenas os formatos que você listar, o que pode encurtar a tarefa.
Valores disponíveis:
glbobjfbxstlusdz3mf
Se você deixar de fora, Meshy gera todos os formatos, exceto
3mf. Meshy gera3mfapenas quando você o lista.
- Name
- auto_size
- Type
- boolean
- padrão false
- Description
Se deve estimar a altura real do objeto no mundo real com visão de IA e redimensionar o modelo a essa altura. Meshy coloca a origem na parte inferior, a menos que você defina
origin_at.
auto_size = true- Name
- origin_at
- Type
- string
- padrão bottom
- Description
Onde colocar a origem do modelo,
bottomoucenter.
- Name
- alpha_thumbnail
- Type
- boolean
- padrão false
- Description
Se também deve renderizar uma prévia com fundo transparente (RGBA), retornada em
alpha_thumbnail_urlao obter a tarefa.thumbnail_urlnão muda.
- Name
- multi_view_thumbnails
- Type
- boolean
- padrão false
- Description
Se também deve renderizar prévias frontal, direita, traseira e esquerda, retornadas em
thumbnail_urlsao obter a tarefa.thumbnail_urlnão muda e continua mostrando a vista frontal. Isso adiciona cerca de 5 segundos à tarefa.
Retornos
O campo result da resposta contém o ID da nova tarefa de Multi-imagem para 3D.
Modos de falha
- Name
400 - Bad Request- Description
A solicitação não pode ser executada. A mensagem de erro indica qual problema foi encontrado. Por exemplo:
- Parâmetro ausente: Nem
image_urlsneminput_task_idforam enviados. - Tarefa de entrada inválida:
input_task_idnão é uma tarefa de Texto para imagem ou Imagem para imagem com statusSUCCEEDED, nem uma de multivista. - Número de imagens inválido:
image_urlsoutexture_image_urlsnão contém de 1 a 4 imagens. - Formato de imagem inválido: Uma imagem em
image_urlsnão está em um formato suportado. - Entradas de textura conflitantes:
texture_image_urlsfoi enviado junto comtexture_image_url, comtexture_prompt, ou comshould_texture: false. - Modelo não suportado para textura multivista:
texture_image_urlsfoi enviado comai_modeligual ameshy-6oumeshy-6-lite, a menos quetexture_modelsejameshy-7oumeshy-n1. - URL inacessível: Meshy não consegue baixar uma imagem em
image_urlsoutexture_image_urls. - Imagem muito grande: Uma imagem em
image_urls,texture_image_urloutexture_image_urlstem mais de 20 MB. - Tamanho de imagem inválido: Uma imagem em
image_urls,texture_image_urloutexture_image_urlstem um lado menor que 32 pixels, ou mais de 178.956.970 pixels (largura × altura). - Resolução não suportada para entrada de múltiplas imagens:
geometry_resolutioné"4k", que este endpoint não suporta. Use2koustandard. - Modelo não suportado para opções de imagem:
image_enhancementfoi enviado comai_model: "meshy-6-lite", ouremove_lightingfoi enviado comai_model: "meshy-6-lite"e seu modelo de textura padrão. - Modelo de textura inválido:
texture_modelnão é um nome de modelo de textura válido. - Modelo de textura não disponível: Uma solicitação texturizada enviou
texture_modeligual ameshy-6oumeshy-6-lite. Multi-imagem para 3D aceita apenas os modelos de textura que texturizam a partir de várias vistas. Enviemeshy-7oumeshy-n1, ou deixetexture_modelde fora. - Opção não suportada para o modelo de textura: A solicitação pede ao modelo de textura uma opção que ele não suporta, como
enable_pbr: truecommeshy-n1ou uma textura4kcommeshy-6-lite. Consulte Modelos.
Corrija a solicitação e envie-a novamente. Consulte Erros.
- Parâmetro ausente: Nem
- Name
401 - Unauthorized- Description
A chave de API está ausente ou é inválida. Verifique o cabeçalho
Authorization.
- Name
402 - Payment Required- Description
Por exemplo:
- Créditos insuficientes: A conta não tem créditos suficientes para esta tarefa, ou a conta atingiu um limite de créditos. Verifique seu saldo de créditos e tente novamente.
- Plano gratuito: Criar uma tarefa requer um plano pago. Faça upgrade do seu plano nas configurações de assinatura e tente novamente.
- Name
403 - Forbidden- Description
A moderação de conteúdo bloqueou o prompt ou uma imagem de entrada. Altere a entrada e tente novamente.
- Name
404 - Not Found- Description
input_task_idnão corresponde a nenhuma das suas tarefas. Verifique o ID da tarefa e envie a solicitação novamente.
- Name
429 - Too Many Requests- Description
Você excedeu seu limite de taxa. Aguarde e tente novamente. Consulte Limites de taxa.
Obter uma tarefa de Multi-imagem para 3D
Retorna uma tarefa de Multi-imagem para 3D pelo seu ID.
Request
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "multi-image-to-3d",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
Parâmetros
- Name
- id
- Type
- path
- Description
O ID da tarefa retornado na resposta de criação.
Retornos
Excluir uma tarefa de Multi-imagem para 3D
Exclui permanentemente uma tarefa de Multi-imagem para 3D, incluindo seus modelos e dados. Você não pode desfazer uma exclusão.
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/multi-image-to-3d/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 você a criou.
Uma tarefa IN_PROGRESS não pode ser excluída. A solicitaçã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
chegue a SUCCEEDED, FAILED ou CANCELED, e então a exclua.
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.
List Multi-Image to 3D tasks
Retorna uma lista das suas tarefas de Multi-imagem para 3D.
Request
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "multi-image-to-3d",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
]
Parâmetros
- Name
- page_num
- Type
- integer
- padrão 1
- Description
O número da página a retornar, até
255. Um valor maior retorna400.
- Name
- page_size
- Type
- integer
- padrão 10
- Description
O número de tarefas por página, até
100.
- Name
- sort_by
- Type
- string
- Description
A ordem de classificação.
Valores disponíveis:
+created_at: mais antigas primeiro-created_at: mais recentes primeiro
Retorno
Uma lista paginada de objetos de tarefa Multi-imagem para 3D.
Transmitir um stream de uma tarefa Multi-imagem para 3D
Transmite as atualizações de uma tarefa Multi-imagem para 3D como Server-Sent Events (SSE).
Request
curl -N https://api.meshy.ai/openapi/v1/multi-image-to-3d/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": "multi-image-to-3d",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
Parâmetros
- Name
- id
- Type
- path
- Description
O ID da tarefa retornado na resposta de criação.
Retorno
Um stream de objetos de tarefa Multi-imagem para 3D 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 Multi-imagem para 3D
Um objeto de tarefa Multi-imagem para 3D descreve uma geração de um modelo 3D a partir de uma a quatro imagens de um objeto. Ele contém o status, o progresso e os arquivos do modelo quando a tarefa é bem-sucedida.
Propriedades
Example Multi-Image to 3D Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "multi-image-to-3d",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
- Name
- id
- Type
- string
- Description
O ID da tarefa. Trate-o como uma string opaca e não dependa do seu formato.
- Name
- type
- Type
- string
- Description
O tipo da tarefa, sempre
multi-image-to-3d.
- Name
- model_urls
- Type
- object
- Description
URLs de download para o modelo 3D gerado, uma para cada formato de arquivo. Um formato que a tarefa não gerou não tem chave, em vez de uma string vazia.
- Name
glb- Type
- string
- Description
O arquivo GLB.
- Name
fbx- Type
- string
- Description
O arquivo FBX.
- Name
obj- Type
- string
- Description
O arquivo OBJ.
- Name
usdz- Type
- string
- Description
O arquivo USDZ.
- Name
mtl- Type
- string
- Description
O arquivo MTL, retornado junto com o arquivo OBJ quando o modelo tem texturas.
- Name
stl- Type
- string
- Description
O arquivo STL.
- Name
3mf- Type
- string
- Description
O arquivo 3MF. Presente apenas quando
target_formatsinclui3mf.
- Name
pre_remeshed_glb- Type
- string
- Description
O arquivo GLB de antes do remesh. Presente apenas quando você criou a tarefa com
should_remesh: trueesave_pre_remeshed_model: true.
- Name
- thumbnail_url
- Type
- string
- Description
URL de download para uma imagem de pré-visualização do modelo. É a mesma que
thumbnail_urls.frontquando esse campo está presente.
- Name
- alpha_thumbnail_url
- Type
- string
- Description
URL de download para uma versão de
thumbnail_urlcom fundo transparente (RGBA). Presente apenas quando você criou a tarefa comalpha_thumbnail: truee a Meshy renderizou a pré-visualização transparente.
- Name
- thumbnail_urls
- Type
- object
- Description
URLs de download para pré-visualizações do modelo 3D vistas de quatro lados. Cada uma é uma URL assinada para um PNG de 512×512, renderizado com os mesmos materiais e iluminação de
thumbnail_url. Você pode usá-las para visualizar o modelo de vários ângulos sem baixar o GLB.Presente apenas quando você criou a tarefa com
multi_view_thumbnails: truee a tarefa atingiu o statusSUCCEEDED. Uma tarefa criada semmulti_view_thumbnails: truenão possui esse campo.- Name
- front
- Type
- string
- Description
A vista frontal, a 0° em torno do eixo vertical. Corresponde a
thumbnail_url.
- Name
- right
- Type
- string
- Description
A vista direita, a 90°.
- Name
- back
- Type
- string
- Description
A vista traseira, a 180°.
- Name
- left
- Type
- string
- Description
A vista esquerda, a 270°.
- Name
- texture_prompt
- Type
- string
- Description
O prompt de texto que guiou a textura.
- Name
- texture_image_urls
- Type
- string[]
- Description
URLs de download para as imagens de referência de textura com as quais você criou a tarefa, na ordem em que foram enviadas. Presente apenas quando você criou a tarefa com
texture_image_urls.
- Name
- ultra_mode
- Type
- boolean
- ⚠ obsoleto
- Description
Consulte
geometry_resolutionem vez disso.
- Name
- geometry_resolution
- Type
- string
- Description
O nível Ultra em que a tarefa foi executada, que é
2k. Uma tarefastandardnão tem esse campo.
- Name
- progress
- Type
- integer
- Description
Quanto da tarefa foi concluído, em porcentagem. É
0até a tarefa começar e100quando ela é bem-sucedida.
- Name
- started_at
- Type
- timestamp
- Description
Horário em que a tarefa começou, em milissegundos Unix. É
0até a tarefa começar.
- Name
- created_at
- Type
- timestamp
- Description
Horário em que a tarefa foi criada, em milissegundos Unix.
- Name
- expires_at
- Type
- timestamp
- Description
Horário em que os resultados da tarefa expiram, em milissegundos Unix.
- Name
- finished_at
- Type
- timestamp
- Description
Horário em que a tarefa terminou, em milissegundos Unix. É
0até a tarefa terminar.
- Name
- status
- Type
- string
- Description
O status da tarefa, um de
PENDING,IN_PROGRESS,SUCCEEDED,FAILEDouCANCELED.
- Name
- texture_urls
- Type
- array
- Description
URLs de download para os mapas de textura que a tarefa gerou, como um array de objetos. Geralmente contém um objeto. Cada objeto tem estes campos:
- Name
base_color- Type
- string
- Description
O mapa de cor base.
- Name
metallic- Type
- string
- Description
O mapa metálico. Não incluído quando você criou a tarefa com
enable_pbr: false.
- Name
normal- Type
- string
- Description
O mapa de normais. Não incluído quando você criou a tarefa com
enable_pbr: false.
- Name
roughness- Type
- string
- Description
O mapa de rugosidade. Não incluído quando você criou a tarefa com
enable_pbr: false.
- Name
emission- Type
- string
- Description
O mapa de emissão. Incluído apenas quando você criou a tarefa com todos os itens a seguir:
ai_model: meshy-6, com seu modelo de textura padrãoenable_pbr: true- uma
texture_resolutionde2kou4k
- Name
- preceding_tasks
- Type
- integer
- Description
O número de tarefas à frente desta na fila. O valor é significativo apenas enquanto a tarefa está
PENDING.
- Name
- task_error
- Type
- object
- Description
Os detalhes do erro quando a tarefa falha. É
null, a menos que o status sejaFAILED. Consulte Erros.
- Name
- consumed_credits
- Type
- integer
- Description
O número de créditos que a tarefa usou. Presente quando o status é
PENDING,IN_PROGRESSouSUCCEEDED. É0para uma tarefaFAILED, porque a Meshy reembolsa os créditos quando uma tarefa falha.