API de Texto para 3D

A etapa do fluxo de trabalho em duas etapas. Envie preview para criar uma tarefa de preview.

Texto que descreve o objeto a ser gerado, com até 800 caracteres. Um texto mais longo retorna 400.

O tipo de malha 3D a ser gerada.

Valores disponíveis:

• standard: uma malha 3D de alto detalhe
• smart-topology: uma malha de Smart Topology. Escolha o modelo com ai_model (meshy-t2 ou meshy-t2.5).

Com smart-topology, o Meshy ignora should_remesh e decimation_mode, e aceita apenas topology: triangle.

O modelo de IA que gera o modelo 3D. Os valores disponíveis dependem de model_type.

Modelos standard (model_type: standard):

• meshy-6-lite
• meshy-6
• meshy-7.1
• latest: Meshy 7.1
• meshy-7 (obsoleto): envie meshy-7.1 em vez disso

Modelos Smart Topology (model_type: smart-topology):

• meshy-t2: topology mais limpa, partes separadas nativamente, saída em triângulos e uma contagem de faces definida por você com target_polycount
• meshy-t2.5 (padrão): detalhe mais nítido para assets de jogos, saída em triângulos e uma contagem de faces definida por você com target_polycount

A passagem de geração de geometria. Aplica-se apenas a tarefas de preview. Um refine com esse parâmetro retorna 400.

Valores disponíveis:

• standard
• 2k: executa a passagem Ultra em 2048³
• 4k: executa a passagem Ultra em 4096³, para detalhe de superfície mais fino

2k requer meshy-7.1, latest ou o meshy-7 obsoleto. 4k requer meshy-7.1 ou latest. Outros modelos retornam 400.

Envie geometry_resolution em vez disso. ultra_mode: true é o mesmo que geometry_resolution: "2k".

Se o modelo deve passar por remesh após a geração. Para o modelo 3D de maior qualidade, envie false.

O número de faces a ser almejado. O resultado pode diferir do alvo, dependendo da geometria. Isso se aplica em dois casos distintos:

• Remesh: com should_remesh: true em um modelo standard. O Meshy remalha (decima) a malha para aproximadamente essa contagem. Se você definir decimation_mode, o Meshy o usa e ignora target_polycount.
• Smart Topology: com model_type: smart-topology e ai_model meshy-t2 ou meshy-t2.5. O Meshy gera o modelo diretamente com essa contagem de faces. Nenhum remesh é executado, e você não precisa de should_remesh.

A tabela a seguir mostra o intervalo e o padrão para cada caso:

Um valor fora do intervalo retorna 400.

Não envie. Esse parâmetro não afeta a saída.

Valores disponíveis:

• off: desativa a simetria
• auto: aplica simetria com base na geometria de entrada
• on: força a simetria durante a geração

A pose do modelo gerado.

Valores disponíveis:

• a-pose: uma pose A
• t-pose: uma pose T
• "" (string vazia): nenhuma pose específica

Envie pose_mode em vez disso. Se o modelo deve ser gerado em pose A ou pose T.

Não envie. O Meshy o ignora.

Se deve verificar prompt em busca de conteúdo prejudicial antes de gerar. Se o Meshy detectar conteúdo prejudicial, a requisição retorna 400 e o Meshy não cria a tarefa.

Os formatos de arquivo a serem gerados. O Meshy gera e retorna apenas esses formatos, o que pode reduzir a duração da tarefa. Se você não enviar esse parâmetro, o Meshy gera todos os formatos, exceto 3mf, que só é gerado quando solicitado.

Valores disponíveis:

• glb
• obj
• fbx
• stl
• usdz
• 3mf

Se também deve renderizar um preview com fundo transparente (RGBA), retornado em alpha_thumbnail_url ao obter a tarefa. thumbnail_url não muda.

Se deve estimar a altura real do objeto no mundo real com visão de IA e redimensionar o modelo para ela. O Meshy coloca a origem na parte inferior, a menos que você defina origin_at.

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 prompt ou mode, está ausente.
• Prompt muito longo: prompt excede o limite de caracteres.
• Modelo não suportado para Ultra: geometry_resolution é 2k ou 4k, com um ai_model que não suporta essa execução.

Corrija a requisição e a envie novamente. Veja Erros.

A chave de API está ausente ou inválida. Verifique o cabeçalho Authorization.

Por exemplo:

• Créditos insuficientes: A conta não tem créditos suficientes para essa 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.

Você excedeu seu limite de taxa. Aguarde e tente novamente. Veja Limites de taxa.

A etapa do fluxo de trabalho de duas etapas. Envie refine para criar uma tarefa de refine.

O ID da tarefa de preview a ser texturizada. A tarefa de preview deve ter o status SUCCEEDED.

Se também deve gerar mapas PBR (metálico, rugosidade e normal) junto com a cor base.

Com ai_model meshy-6, o Meshy também gera um mapa de emissão, exceto em texture_resolution: 8k. meshy-6-lite, meshy-7, meshy-7.1 e latest não geram um mapa de emissão. Um refine de um preview meshy-t2 ou meshy-t2.5 que não define ai_model também não gera.

A resolução da textura de cor base. Aplica-se apenas a tarefas de refine. Um preview com este parâmetro retorna 400.

Valores disponíveis:

• 2k: 2048×2048
• 4k: 4096×4096
• 8k: 8192×8192

Resoluções mais altas capturam mais detalhes de superfície. 4k e 8k exigem ai_model meshy-6, meshy-7.1 ou latest. Em 8k, o Meshy não gera um mapa de emissão.

Envie texture_resolution em vez disso. hd_texture: true é o mesmo que texture_resolution: "4k". Se você enviar ambos, o Meshy usa texture_resolution.

Texto que orienta a texturização, com até 800 caracteres. Um texto mais longo retorna 400. Envie texture_prompt ou texture_image_url, não ambos. Se você enviar ambos, o Meshy usa texture_prompt.

Uma imagem 2D que orienta a texturização, 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.

O modelo de IA que texturiza a malha.

Valores disponíveis:

• meshy-6-lite
• meshy-6
• meshy-7.1
• latest: Meshy 7.1
• meshy-7 (obsoleto): envie meshy-7.1 em vez disso

Deixe de fora para usar o modelo da tarefa de preview, de modo que o preview e seu refine sejam executados no mesmo modelo de ponta a ponta. Envie um valor para substituí-lo. Um latest explícito é resolvido da mesma forma que na tarefa de preview, de modo que um preview latest e seu refine latest sempre usam o mesmo modelo de textura.

Se deve verificar texture_prompt e texture_image_url em busca de conteúdo prejudicial antes de gerar. Se o Meshy detectar conteúdo prejudicial, a requisição retorna 400 e o Meshy não cria a tarefa.

Se deve remover realces e sombras da textura de cor base. O resultado mais limpo funciona melhor sob iluminação personalizada.

Só tem efeito quando ai_model é meshy-6. meshy-7.1 e latest aceitam o parâmetro e o ignoram, assim como um refine de um preview meshy-t2 ou meshy-t2.5 que não define ai_model. Enviá-lo com meshy-6-lite retorna 400.

Os formatos de arquivo a serem gerados. O Meshy gera e retorna apenas esses formatos, o que pode encurtar a tarefa. Se você deixar de fora, o Meshy gera todos os formatos, exceto 3mf, que só gera quando você o solicita.

Valores disponíveis:

• glb
• obj
• fbx
• stl
• usdz
• 3mf

Se também deve renderizar um preview com fundo transparente (RGBA), retornado em alpha_thumbnail_url ao obter a tarefa. thumbnail_url não muda.

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.

A requisição não pode ser executada. A mensagem de erro informa qual problema foi encontrado. Por exemplo:

• Invalid task ID: preview_task_id é inválido ou não corresponde a nenhuma de suas tarefas de preview.
• Task not ready: A tarefa de preview ainda não foi concluída com sucesso.
• Model mismatch: O modelo de IA da tarefa de preview não funciona com o modelo de refine solicitado.
• Unsupported model for remove_lighting: remove_lighting foi enviado com ai_model: "meshy-6-lite".

Corrija a requisição e a envie novamente. Veja Errors.

A chave de API está ausente ou inválida. Verifique o cabeçalho Authorization.

Por exemplo:

• Insufficient credits: 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.
• Free plan: Criar uma tarefa requer um plano pago. Faça upgrade do seu plano nas configurações de assinatura e tente novamente.

Você excedeu seu limite de taxa. Aguarde e tente novamente. Veja Rate limits.

O ID da tarefa a partir da resposta de criação.

O ID da tarefa a ser excluída.

O número da página a ser retornada.

O número de tarefas por página, até 100.

A ordem de classificação.

Valores disponíveis:

• +created_at: mais antigas primeiro
• -created_at: mais recentes primeiro

O ID da tarefa retornado na resposta de criação.

O ID da tarefa. Trate-o como uma string opaca e não dependa do seu formato.

O tipo da tarefa, text-to-3d-preview para uma tarefa preview ou text-to-3d-refine para uma tarefa refine.

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.

O prompt que você enviou para criar a tarefa, sem modificações.

O prompt de texto que você enviou para guiar a texturização no estágio refine.

Consulte geometry_resolution em vez disso.

O nível Ultra em que a tarefa preview foi executada, 2k ou 4k. O campo está ausente para standard.

URL de download para a imagem que você enviou para guiar a texturização.

URL de download para uma imagem de miniatura do modelo 3D.

URL de download para uma versão de thumbnail_url com fundo transparente (RGBA). Presente somente quando você criou a tarefa com alpha_thumbnail: true e a Meshy renderizou a prévia transparente.

Não dependa deste campo, pois uma versão futura o removerá. URL de download para o vídeo de preview.

Quanto da tarefa foi concluído, em porcentagem. É 0 até a tarefa começar e 100 quando ela é concluída com sucesso.

Horário em que a tarefa começou, em milissegundos Unix. É 0 até a tarefa começar.

Horário em que a tarefa foi criada, em milissegundos Unix.

Horário em que a tarefa foi concluída, em milissegundos Unix. É 0 até a tarefa ser concluída.

O status da tarefa, um de PENDING, IN_PROGRESS, SUCCEEDED, FAILED ou CANCELED.

URLs de download para os mapas de textura gerados, como um array de objetos. Geralmente contém um objeto. Cada objeto tem estes campos:

O número de tarefas à frente desta na fila. O valor é significativo somente enquanto a tarefa está PENDING.

Os detalhes do erro quando a tarefa falha. Consulte Erros.

O número de créditos que a tarefa usou. Presente quando o status é PENDING, IN_PROGRESS ou SUCCEEDED. É 0 para uma tarefa FAILED, porque a Meshy reembolsa os créditos quando uma tarefa falha.