API de Texto para 3D

Este campo deve ser definido como "preview" ao criar uma tarefa de preview.

Descreve que tipo de objeto é o modelo 3D. Máximo de 800 caracteres.

Especifica o tipo de geração de malha 3D.

Valores disponíveis:

• standard: Geração de malha 3D regular de alto detalhe.
• smart-topology: Escolha o modelo Smart Topology com ai_model (meshy-t2).
• lowpoly (obsoleto, a ser descontinuado a 30 de outubro de 2026): Gera uma malha low-poly otimizada para polígonos mais limpos. Recomendamos o Meshy T2 em alternativa: smart-topology com meshy-t2.

ID do modelo a utilizar. Os valores disponíveis dependem de model_type.

Geração standard (model_type: standard):

• meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
• meshy-7 (obsoleto): utilize meshy-7.1 em alternativa.

Geração Smart Topology (model_type: smart-topology):

• meshy-t2 (predefinição): o modelo Smart Topology — topology mais limpa, partes nativamente separadas, saída em triângulos e uma contagem de faces que pode definir com target_polycount.

Passagem de geração de geometria. 2k executa a passagem Ultra a 2048³; 4k executa-a a 4096³ para o detalhe de superfície mais fino.

Valores disponíveis: standard, 2k, 4k

Utilize geometry_resolution em alternativa. ultra_mode: true é equivalente a geometry_resolution: "2k".

Controla se a fase de remesh está ativada. Para o modelo de maior qualidade, recomendamos definir should_remesh como false.

Número alvo de polígonos (faces) no resultado. A contagem real pode desviar-se do alvo consoante a geometria.

target_polycount tem efeito em dois casos independentes:

• Remesh — com should_remesh: true num modelo standard. A malha sofre remesh (decimação) para aproximadamente esta contagem. Intervalo de 100 a 300 000, predefinição 30 000. Se decimation_mode estiver definido, tem prioridade e target_polycount é ignorado.
• Smart Topology — com model_type: smart-topology e ai_model: meshy-t2. O modelo é gerado diretamente com esta contagem de faces; não é executado nenhum remesh e should_remesh não é necessário. Intervalo de 100 a 15 000, predefinição 4000.

Obsoleto. Este parâmetro já não afeta o resultado.

O campo symmetry_mode controla o comportamento de simetria durante o processo de geração do modelo.

Os valores válidos são:

• off: Desativa a simetria.
• auto: Determina e aplica automaticamente a simetria com base na geometria de entrada.
• on: Impõe a simetria durante a geração.

Especifica o pose_mode para o modelo gerado.

Valores disponíveis:

• a-pose: Gera o modelo numa pose A.
• t-pose: Gera o modelo numa pose T.
• "" (cadeia vazia): Nenhuma pose específica aplicada.

Utilize pose_mode em alternativa. Se deve gerar o modelo numa pose A/T.

Não suportado pelo Meshy-6. Pedidos que utilizem o Meshy-6 irão ignorar art_style, e algumas combinações podem causar erros. Valores disponíveis: realistic, sculpture.

Quando definido como true, o conteúdo de entrada será automaticamente analisado em busca de conteúdo potencialmente prejudicial. Se for detetado conteúdo prejudicial, a tarefa não avançará para a geração.

O texto de prompt será analisado.

Especifica que formatos de ficheiro 3D incluir no resultado. Apenas os formatos solicitados serão gerados e devolvidos, o que pode reduzir o tempo de conclusão da tarefa. Quando omitido, todos os formatos suportados são incluídos.

Valores disponíveis: glb, obj, fbx, stl, usdz, 3mf

Quando definido como true, a tarefa gera adicionalmente uma versão com fundo transparente (RGBA) do preview e devolve-a como alpha_thumbnail_url na resposta GET. O campo thumbnail_url existente permanece inalterado.

Quando definido como true, o serviço utiliza visão por IA para estimar automaticamente a altura real do objeto e redimensionar o modelo em conformidade. A origem assume bottom por predefinição, a menos que origin_at seja explicitamente definido.

O pedido foi inaceitável. Causas comuns:

• Parâmetro em falta: Falta um parâmetro obrigatório (por exemplo, prompt, mode).
• Parâmetro inválido: art_style não corresponde a nenhum dos valores permitidos.
• Prompt demasiado longo: O prompt excede o limite de caracteres.
• Modelo não suportado para low poly: ai_model: "meshy-6-lite" não suporta model_type: "lowpoly".
• Modelo não suportado para Ultra: geometry_resolution requer meshy-7.1 ou latest.

Falha na autenticação. Verifique a sua chave de API.

Créditos insuficientes para realizar esta tarefa.

Excedeu o seu limite de taxa.

Este campo deve ser definido como "refine" ao criar uma tarefa de refine.

O id da tarefa de pré-visualização correspondente.

O estado da tarefa de pré-visualização indicada deve ser SUCCEEDED.

Gera mapas PBR (metallic, roughness, normal) além da cor base. Também é incluído um mapa de emissão quando ai_model é meshy-6, exceto em texture_resolution: 8k (neste caso não é produzido nenhum mapa de emissão). meshy-6-lite, meshy-7.1 e latest não produzem mapa de emissão, e o mesmo acontece com um refine de uma pré-visualização meshy-t2 que não define ai_model.

Resolução da textura de cor base. Uma de 2k (2048×2048), 4k (4096×4096) ou 8k (8192×8192). Resoluções mais elevadas captam mais detalhe de superfície. Aplica-se apenas ao mode refine.

Utilize texture_resolution em vez deste — equivalente a texture_resolution: "4k". Quando ambos são definidos, texture_resolution tem precedência.

Forneça um prompt de texto adicional para orientar o processo de texturização. Máximo de 800 caracteres.

Forneça uma imagem 2d para orientar o processo de texturização. Atualmente suportamos os formatos .jpg, .jpeg, .png e .webp.

Tamanho máximo do ficheiro: 20 MB.

Existem duas formas de fornecer a imagem:

• URL publicamente acessível: Um URL acessível a partir da internet pública
• Data URI: Um data URI da imagem codificado em base64. Exemplo de um data URI: data:image/jpeg;base64,<your base64-encoded image data>

ID do modelo a utilizar para o refine.

Valores disponíveis:

• meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
• meshy-7 (obsoleto): utilize meshy-7.1 em vez deste.

Omita este parâmetro para herdar o modelo utilizado pela tarefa de pré-visualização, o que mantém uma pré-visualização e o seu refine no mesmo modelo do início ao fim. Indique um valor explícito para substituir essa herança.

Quando definido como true, o conteúdo de entrada será automaticamente analisado em busca de conteúdo potencialmente prejudicial. Se for detetado conteúdo prejudicial, a tarefa não avançará para a geração.

Tanto o texto de texture_prompt como a imagem de texture_image_url serão analisados.

Remove realces e sombras da textura de cor base, produzindo um resultado mais limpo que funciona melhor em configurações de iluminação personalizadas.

Especifica quais os formatos de ficheiro 3D a incluir no resultado. Apenas os formatos solicitados serão gerados e devolvidos, o que pode reduzir o tempo de conclusão da tarefa. Quando omitido, são incluídos todos os formatos suportados.

Valores disponíveis: glb, obj, fbx, stl, usdz, 3mf

Quando definido como true, a tarefa gera adicionalmente uma versão com fundo transparente (RGBA) da pré-visualização e devolve-a como alpha_thumbnail_url na resposta GET. O campo existente thumbnail_url permanece inalterado.

Quando definido como true, o serviço utiliza visão por IA para estimar automaticamente a altura real do objeto e redimensionar o modelo em conformidade. A origem terá como predefinição bottom, a menos que origin_at seja explicitamente definido.

O pedido foi inaceitável. Causas comuns:

• ID de tarefa inválido: O preview_task_id é inválido ou não existe.
• Tarefa não pronta: A tarefa de pré-visualização ainda não foi concluída com sucesso.
• Incompatibilidade de modelo: O modelo de IA da tarefa de pré-visualização é incompatível com o modelo de refine solicitado.
• Modelo não suportado para remove_lighting: remove_lighting é definido com ai_model: "meshy-6-lite".

A autenticação falhou. Verifique a sua chave de API.

Créditos insuficientes para realizar esta tarefa.

A tarefa de pré-visualização especificada por preview_task_id não foi encontrada.

Excedeu o seu limite de taxa.

Identificador único da tarefa de Texto para 3D a obter.

O ID da tarefa de Texto para 3D a eliminar.

Número de página para paginação.

Limite de itens por página. O máximo permitido é 100 itens.

Campo pelo qual ordenar.

Valores disponíveis:

• +created_at: Ordenar por data de criação, por ordem ascendente.
• -created_at: Ordenar por data de criação, por ordem descendente.

Identificador único da tarefa de Texto para 3D a transmitir.

Identificador único da tarefa. Embora utilizemos um UUID k-sortable para os ids de tarefa como detalhe de implementação, não deve fazer quaisquer suposições sobre o formato do id.

Tipo da tarefa Texto para 3D. Os valores possíveis são text-to-3d-preview para tarefas da etapa de preview e text-to-3d-refine para tarefas da etapa de refine.

URL para download do ficheiro de modelo 3D com textura gerado pela Meshy. A propriedade de um formato será omitida se o formato não for gerado, em vez de ser devolvida uma string vazia.

Este é o prompt não modificado que foi utilizado para criar a tarefa.

Mantido para compatibilidade com versões anteriores. Este campo não tem qualquer impacto funcional nos modelos gerados.

O art_style não modificado que foi utilizado para criar a tarefa de preview. Não suportado pelo Meshy-6.

Mantido para compatibilidade com versões anteriores. Este campo não tem qualquer impacto funcional nos modelos gerados.

Prompt de texto adicional fornecido para guiar o processo de texturização durante a etapa de refine.

Obsoleto; consulte geometry_resolution em vez disso.

O nível Ultra em que a tarefa de preview foi executada (2k ou 4k); omitido para standard.

URL para download da imagem de textura que foi utilizada para guiar o processo de texturização.

URL para download da imagem de miniatura do ficheiro do modelo.

URL para download de uma versão com fundo transparente (RGBA) de thumbnail_url. Apenas presente quando a tarefa foi criada com alpha_thumbnail: true e a pré-visualização transparente foi renderizada com sucesso; caso contrário, este campo é omitido.

URL para download do vídeo de pré-visualização. Será removido numa versão futura.

Progresso da tarefa. Se a tarefa ainda não tiver iniciado, esta propriedade será 0. Assim que a tarefa for bem-sucedida, isto passará a 100.

Carimbo de data/hora de quando a tarefa foi iniciada, em milissegundos. Se a tarefa ainda não tiver iniciado, esta propriedade será 0.

Carimbo de data/hora de quando a tarefa foi criada, em milissegundos.

Carimbo de data/hora de quando a tarefa foi concluída, em milissegundos. Se a tarefa ainda não tiver sido concluída, esta propriedade será 0.

Estado da tarefa. Os valores possíveis são um de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Uma matriz de objetos de URL de textura gerados pela tarefa. Normalmente, esta contém apenas um objeto de URL de textura. Cada URL de textura tem as seguintes propriedades:

A contagem de tarefas precedentes.

Detalhes do erro para tarefas falhadas. Consulte Erros para a referência completa do objeto task_error.

O número de créditos consumidos por esta tarefa. Presente quando o estado da tarefa é PENDING, IN_PROGRESS, ou SUCCEEDED. Devolve 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).