Imagem para 3D API
Transforme uma imagem em um modelo 3D, com ou sem texturas, nos formatos que você escolher. Envie a imagem, ou use o resultado de uma tarefa de Texto para imagem ou Imagem para imagem.
Criar uma tarefa de Imagem para 3D
Cria uma tarefa de Imagem para 3D. A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa costuma levar, consulte Tempos de processamento.
Request
# Simple request with required params
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_url": "<your publicly accessible image url or base64-encoded data URI>"
}'
# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_url": "<your publicly accessible image url or base64-encoded data URI>",
"ai_model": "meshy-7.1",
"geometry_resolution": "4k",
"enable_pbr": true,
"should_remesh": true,
"target_polycount": 100000,
"should_texture": true,
"pose_mode": "a-pose",
"target_formats": ["glb"]
}'
# Textured with Meshy N1 from the input image
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_url": "<your publicly accessible 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_url. O ID de uma tarefa de Texto para imagem ou Imagem para imagem cuja imagem você deseja usar como entrada. A tarefa deve ser uma que você criou com a API, deve ter o statusSUCCEEDEDe deve ter produzido exatamente uma imagem.
- Name
- image_url
- Type
- string
- Obrigatório
- Description
Obrigatório, a menos que você envie
input_task_id. A imagem a ser transformada em um modelo 3D, como uma URL pública ou um Data URI codificado em base64, comodata:image/jpeg;base64,<seus dados de imagem codificados em base64>. Se você enviar ambos, o Meshy usainput_task_id.A imagem deve ser um arquivo JPG, JPEG, PNG ou 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).
- Name
- model_type
- Type
- string
- padrão standard
- Description
O tipo de malha 3D a ser gerada.
Valores disponíveis:
standard: uma malha de alto detalhesmart-topology: uma malha de um modelo Smart Topology, que você escolhe comai_model(meshy-t2oumeshy-t2.5)
Com
smart-topology, o Meshy ignorashould_remesh,save_pre_remeshed_modeledecimation_mode, e aceita apenastopology: triangle.
- Name
- ai_model
- Type
- string
- padrão latest
- Description
O modelo de IA que gera o modelo 3D. Os valores disponíveis dependem de
model_type.Modelos padrão (
model_type: standard):latest: Meshy 7.1meshy-7.1meshy-6meshy-6-litemeshy-7(obsoleto): usemeshy-7.1em vez disso. Ele se aposenta em 31 de dezembro de 2026.
Modelos Smart Topology (
model_type: smart-topology) produzem triângulos, em uma contagem de faces que você pode definir comtarget_polycount:meshy-t2: topologia mais limpa e partes nativamente separadasmeshy-t2.5(padrão): detalhe mais nítido para assets de jogos
Consulte Modelos para saber qual modelo se adapta ao seu projeto, como um personagem de jogo ou uma impressão 3D.
- Name
- geometry_resolution
- Type
- string
- padrão standard
- Description
A etapa de geração de geometria.
Valores disponíveis:
standard2k: executa a etapa Ultra em 2048³4k: executa a etapa Ultra em 4096³, para o máximo de detalhe de superfície
2kprecisa demeshy-7.1,latest, ou domeshy-7obsoleto.4kprecisa demeshy-7.1oulatest.
- Name
- ultra_mode
- Type
- boolean
- ⚠ obsoleto
- padrão false
- Description
Use
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, efalseignora a texturização e retorna uma malha sem textura.
should_texture = true- Name
- texture_model
- Type
- string
- padrão depends on ai_model
- Description
O modelo de IA que texturiza o modelo 3D, na mesma tarefa. Omita 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ênciameshy-6-lite: Meshy 6 Lite, uma textura em 2K com o menor customeshy-6: Meshy 6, apenas como padrão paraai_model: meshy-6
Todo
ai_modelaceitameshy-7,meshy-n1emeshy-6-lite. Uma opção que o modelo de textura escolhido não suporta retorna400. Commeshy-n1, um modelo gerado com mais de 7.999.999 triângulos falha a tarefa, e o Meshy reembolsa os créditos. Comshould_texture: false, o Meshy ignoratexture_model, mas um valor desconhecido ainda retorna400.Consulte Modelos para saber o que cada modelo de textura faz e qual escolher.
- Name
- enable_pbr
- Type
- boolean
- padrão false
- Description
Se deve também gerar mapas PBR (metálico, rugosidade e normal) além da cor base.
truerequershould_texture: true, e retorna400comshould_texture: false. Comtexture_model: meshy-n1,trueretorna400.O modelo de textura Meshy 6 também gera um mapa de emissão, exceto em
texture_resolution: 8k.
- Name
- texture_resolution
- Type
- string
- padrão 2k
- Description
O tamanho da textura de cor base. Uma textura maior captura mais detalhe de superfície.
Valores disponíveis:
2k: 2048×20484k: 4096×40968k: 8192×8192
4ke8kprecisam do modelo de textura Meshy 7 ou Meshy 6, e retornam400com os outros. Em8k, o Meshy não produz um mapa de emissão.
- Name
- hd_texture
- Type
- boolean
- ⚠ obsoleto
- padrão false
- Description
Use
texture_resolutionem vez disso.hd_texture: trueé o mesmo quetexture_resolution: "4k". Se você enviar ambos, o 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 que guia a textura, como uma URL pública ou um Data URI codificado em base64, como
data:image/jpeg;base64,<seus dados de imagem codificados em base64>. A imagem deve ser um arquivo JPG, JPEG, PNG ou 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).O Meshy guia a textura usando apenas um entre
texture_promptetexture_image_url. Se você enviar ambos, o Meshy usatexture_prompt. Para o custo em créditos da texturização, consulte Preços.Com
texture_model: meshy-n1, o Meshy texturiza a partir dessa imagem como a vista frontal, ou a partir da imagem de entrada quando você a omite.Texturizar a partir de uma imagem pode não funcionar bem quando o formato da imagem difere muito da geometria do modelo 3D.
- Name
- should_remesh
- Type
- boolean
- padrão true (meshy-6-lite), false (other models)
- Description
Se deve executar a fase de remesh. Para o modelo 3D de mais alta qualidade, defina como
false.
should_remesh = true- Name
- topology
- Type
- string
- padrão triangle
- Description
O tipo de face do modelo remeshado.
Valores disponíveis:
quad: uma malha predominantemente de quadstriangle: uma malha de triângulos decimada
A saída do Smart Topology é apenas triangular, então
quadcommeshy-t2oumeshy-t2.5retorna400. Comtexture_model: meshy-n1,quadretorna400quando o modelo é remeshado, o quemeshy-6-litefaz por padrão.
- Name
- decimation_mode
- Type
- integer
- Description
Contagem de faces adaptativa, por nível. Quando você a define, o 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 deve também armazenar um GLB do modelo antes da fase de remesh. O Meshy o retorna em
model_urls.pre_remeshed_glb.
- Name
- target_polycount
- Type
- integer
- Description
O número de faces a atingir. O resultado pode diferir da meta, dependendo da geometria do modelo.
Aplica-se em dois casos separados:
- Remesh: Quando
should_remeshétrueem um modelostandard, o Meshy decima a malha para cerca dessa contagem. Se você definirdecimation_mode, o Meshy o usa e ignoratarget_polycount. - Smart Topology: Quando
model_typeésmart-topologyeai_modelémeshy-t2oumeshy-t2.5, o Meshy gera o modelo com essa contagem de faces. Nenhum remesh é executado, e você não precisa deshould_remesh.
O intervalo e o padrão dependem do caso:
Caso Intervalo Padrão Remesh 100a30000030000meshy-t2100a150004000meshy-t2.5100a3000015000Um valor fora do intervalo retorna
400.Para um asset de jogo low-poly, use um modelo Smart Topology em vez de remeshar um modelo padrão. Consulte Modelos.
- Remesh: Quando
- Name
- symmetry_mode
- Type
- string
- ⚠ obsoleto
- padrão auto
- Description
Omita, pois não afeta a saída. Seus valores controlavam a simetria durante a geração:
off: sem simetriaauto: simetria escolhida a partir da 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, omitapose_modeeis_a_t_pose.
- Name
- is_a_t_pose
- Type
- boolean
- ⚠ obsoleto
- padrão false
- Description
Use
pose_modeem vez disso. Se deve gerar o modelo em pose A ou pose T.
- Name
- surface_mode
- Type
- string
- ⚠ obsoleto
- Description
Use
ai_modelem vez disso. Não afeta a saída, porque a geração de modelo que ele selecionava está aposentada.Os valores aceitos são
organicehard. Qualquer outro valor retorna400.
- Name
- image_enhancement
- Type
- boolean
- padrão true
- Description
Se deve otimizar a imagem de entrada antes de gerar.
falsemantém o visual exato da imagem de entrada, sem processamento de estilo.Funciona apenas com
meshy-6,meshy-7.1oulatest. Commeshy-6-liteoumodel_type: smart-topology, retorna400.
- Name
- remove_lighting
- Type
- boolean
- padrão true
- Description
Se deve remover realces e sombras da textura de cor base. O resultado é mais limpo e funciona melhor sob sua própria iluminação.
Só tem efeito com o modelo de textura Meshy 6, e um modelo de textura que não o suporta retorna
400paratrue. Commodel_type: smart-topology, ou comai_model: meshy-6-litee seu modelo de textura padrão, enviá-lo retorna400.
- Name
- moderation
- Type
- boolean
- padrão false
- Description
Se deve examinar essas entradas em busca de conteúdo nocivo antes de gerar:
image_urltexture_image_urltexture_prompt
Se o Meshy detectar conteúdo nocivo, a requisição retorna
400e o Meshy não cria a tarefa.
- Name
- target_formats
- Type
- string[]
- Description
Os formatos de arquivo a gerar. O Meshy gera e retorna apenas os formatos que você listar, o que pode encurtar a tarefa. Se você omitir, o Meshy gera todos os formatos, exceto
3mf, que você só obtém se o listar.Valores disponíveis:
glbobjfbxstlusdz3mf
- 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 para essa altura. O Meshy coloca a origem na parte inferior, a menos que você defina
origin_at.
- Name
- alpha_thumbnail
- Type
- boolean
- padrão false
- Description
Se deve também renderizar uma prévia com fundo transparente (RGBA), retornada em
alpha_thumbnail_urlquando você obtém a tarefa.thumbnail_urlnão muda.
- Name
- multi_view_thumbnails
- Type
- boolean
- padrão false
- Description
Se deve também renderizar prévias frontal, direita, traseira e esquerda, retornadas em
thumbnail_urlsquando você obtém a tarefa.thumbnail_urlnão muda e continua mostrando a vista frontal. Isso adiciona cerca de 5 segundos à tarefa.
auto_size = true- Name
- origin_at
- Type
- string
- padrão bottom
- Description
Onde colocar a origem do modelo,
bottomoucenter.
Retornos
O campo result da resposta contém o ID da nova tarefa de Imagem para 3D.
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: Nem
image_urlneminput_task_idforam enviados. - Tarefa de entrada inválida:
input_task_idnão é uma tarefa de Texto para imagem ou Imagem para imagem com statusSUCCEEDEDque produziu exatamente uma imagem. - Formato de imagem inválido: A imagem de
image_urlnão é um arquivo JPG, JPEG, PNG ou WebP. - URL inacessível: O Meshy não consegue baixar a imagem de
image_url, porque a URL retorna404ou expira o tempo de espera. - Imagem muito grande: A imagem de
image_urloutexture_image_urltem mais de 20 MB. - Tamanho de imagem inválido: A imagem de
image_urloutexture_image_urltem um lado menor que 32 pixels, ou mais de 178.956.970 pixels (largura × altura). - Data URI inválido: A string base64 está malformada.
- Combinação de parâmetros inválida:
enable_pbrétrue, eshould_textureéfalse. - Modelo não suportado para Ultra:
geometry_resolutioné2kou4k, com umai_modelque não consegue executá-lo. - Modelo não suportado para opções de imagem: um destes:
image_enhancementfoi enviado comai_model: "meshy-6-lite"oumodel_type: "smart-topology".remove_lightingfoi enviado commodel_type: "smart-topology", ou comai_model: "meshy-6-lite"e seu modelo de textura padrão.
- Modelo de textura inválido:
texture_modelnão é um dos valores disponíveis. - Modelo de textura não disponível:
texture_modelémeshy-6com umai_modeldiferente demeshy-6. Enviemeshy-7,meshy-n1oumeshy-6-lite, ou omita. - Opção não suportada para o modelo de textura: A requisição solicita 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 requisiçã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 requisiçã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 Imagem para 3D
Retorna uma tarefa Imagem para 3D pelo seu ID.
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "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",
"emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.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.
Retorna
Excluir uma tarefa de Imagem para 3D
Exclui permanentemente uma tarefa de 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/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 rota
- 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 na sua criação.
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
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.
Listar tarefas de Imagem para 3D
Retorna uma lista das suas tarefas de Imagem para 3D.
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "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",
"emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.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 ser retornada, 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 antigos primeiro-created_at: mais recentes primeiro
Retornos
Uma lista paginada de objetos de tarefa de Imagem para 3D.
Transmitir uma tarefa de Imagem para 3D em stream
Transmite as atualizações de uma tarefa de Imagem para 3D como Server-Sent Events (SSE).
Request
curl -N https://api.meshy.ai/openapi/v1/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": "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",
"emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
Parâmetros
- Name
- id
- Type
- path
- Description
O ID da tarefa obtido na resposta de criação.
Retornos
Um stream de objetos de tarefa de 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 Imagem para 3D
Um objeto de tarefa Imagem para 3D descreve uma geração de um modelo 3D a partir de uma imagem. Ele contém o status, o progresso e os arquivos do modelo quando a tarefa é bem-sucedida.
Propriedades
Example Image to 3D Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "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": "",
"texture_image_url": "",
"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",
"emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.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
image-to-3d.
- Name
- model_urls
- Type
- object
- Description
URLs de download para o modelo 3D gerado, uma por 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 um 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 3D. Quando
thumbnail_urlsestá presente, é a mesma imagem quethumbnail_urls.front. A Meshy a mantém para compatibilidade retroativa.
- 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 a partir de quatro lados. Cada valor é uma URL assinada para um PNG de 512×512, renderizado com os mesmos materiais e iluminação que
thumbnail_url. Use-as para pré-visualizar o modelo a partir de vários ângulos, por exemplo em um pipeline em lote, sem baixar o GLB.Presente apenas quando você criou a tarefa com
multi_view_thumbnails: truee a tarefa atingiuSUCCEEDED. Tarefas criadas semmulti_view_thumbnails: truenão incluem este campo.- Name
- front
- Type
- string
- Description
A visão frontal, a 0° em torno do eixo vertical. Corresponde a
thumbnail_url.
- Name
- right
- Type
- string
- Description
A visão à direita, a 90°.
- Name
- back
- Type
- string
- Description
A visão traseira, a 180°.
- Name
- left
- Type
- string
- Description
A visão à esquerda, a 270°.
- Name
- texture_prompt
- Type
- string
- Description
O prompt de texto que guiou a textura.
- Name
- texture_image_url
- Type
- string
- Description
URL de download para a imagem que guiou a textura.
- Name
- ultra_mode
- Type
- boolean
- ⚠ obsoleto
- Description
Leia
geometry_resolutionem vez disso.
- Name
- geometry_resolution
- Type
- string
- Description
O nível Ultra em que a tarefa foi executada,
2kou4k. Uma tarefastandardnão inclui este campo.
- Name
- progress
- Type
- integer
- Description
Quanto da tarefa está concluído, em porcentagem. É
0até a tarefa começar e100quando é 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 o resultado da tarefa expira, 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
Os mapas de textura que a tarefa gerou, como um array de objetos. Geralmente contém um objeto, com estes campos:
- Name
base_color- Type
- string
- Description
URL de download para o mapa de cor base.
- Name
metallic- Type
- string
- Description
URL de download para o mapa metálico. O campo está ausente quando você criou a tarefa com
enable_pbr: false.
- Name
normal- Type
- string
- Description
URL de download para o mapa de normais. O campo está ausente quando você criou a tarefa com
enable_pbr: false.
- Name
roughness- Type
- string
- Description
URL de download para o mapa de rugosidade. O campo está ausente quando você criou a tarefa com
enable_pbr: false.
- Name
emission- Type
- string
- Description
URL de download para o mapa de emissão. A Meshy o inclui apenas quando você criou a tarefa com todos estes:
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. É
nulla menos que o status sejaFAILED. Veja 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.