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 gerar, até 800 caracteres. Um texto mais longo devolve 400.

O tipo de malha 3D a gerar.

Valores disponíveis:

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

Com smart-topology, a 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 alternativa

Modelos Smart Topology (model_type: smart-topology):

• meshy-t2: topologia mais limpa, partes separadas nativamente, output em triângulos e uma contagem de faces definida com target_polycount
• meshy-t2.5 (predefinição): detalhe mais nítido para assets de jogos, output em triângulos e uma contagem de faces definida com target_polycount

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

Valores disponíveis:

• standard
• 2k: executa a passagem Ultra a 2048³
• 4k: executa a passagem Ultra a 4096³, para um 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 devolvem 400.

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

Se o modelo deve ser remeshed após a geração. Para obter o modelo 3D de maior qualidade, envie false.

O número de faces a atingir. O resultado pode diferir do alvo, dependendo da geometria. Aplica-se em dois casos distintos:

• Remesh: com should_remesh: true num modelo standard. A Meshy aplica remesh (decima) a malha para aproximadamente esta contagem. Se definir decimation_mode, a Meshy utiliza-o e ignora target_polycount.
• Smart Topology: com model_type: smart-topology e ai_model meshy-t2 ou meshy-t2.5. A Meshy gera o modelo diretamente com esta contagem de faces. Não é executado nenhum remesh, e não precisa de should_remesh.

A tabela seguinte mostra o intervalo e a predefinição para cada caso:

Um valor fora do intervalo devolve 400.

Não o inclua. Este parâmetro não afeta o resultado.

Valores disponíveis:

• off: desativa a simetria
• auto: aplica simetria com base na geometria de entrada
• on: impõe 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): sem pose específica

Envie pose_mode em alternativa. Se o modelo deve ser gerado numa pose A ou numa pose T.

Não o inclua. A Meshy ignora-o.

Se deve verificar prompt para detetar conteúdo prejudicial antes de gerar. Se a Meshy detetar conteúdo prejudicial, o pedido devolve 400 e a Meshy não cria a tarefa.

Os formatos de ficheiro a gerar. A Meshy gera e devolve apenas estes formatos, o que pode encurtar a tarefa. Se não o incluir, a Meshy gera todos os formatos exceto 3mf, que apenas gera quando é solicitado.

Valores disponíveis:

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

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

Se deve estimar a altura real do objeto com visão por IA e redimensionar o modelo em conformidade. A Meshy coloca a origem na base, a menos que defina origin_at.

O pedido não pode ser executado. A mensagem de erro indica qual o problema encontrado. Por exemplo:

• Parâmetro em falta: Falta um parâmetro obrigatório, como prompt ou mode.
• Prompt demasiado 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 o consegue executar.

Corrija o pedido e envie-o novamente. Consulte Erros.

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

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 o seu saldo de créditos e tente novamente.
• Plano gratuito: Criar uma tarefa requer um plano pago. Atualize o seu plano nas definições de subscrição e tente novamente.

A moderação de conteúdo bloqueou o prompt ou uma imagem de entrada. Altere a entrada e tente novamente.

Excedeu o seu limite de taxa. Aguarde e tente novamente. Consulte Limites de taxa.

O passo do fluxo de trabalho de dois passos. Envie refine para criar uma tarefa de refine.

O ID da tarefa de preview a texturizar. A tarefa de preview tem de ter o estado SUCCEEDED.

Se também deve gerar mapas PBR (metallic, roughness e normal) juntamente com a cor base.

Com ai_model meshy-6, a 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 mapa de emissão. Também não o faz um refine de um preview meshy-t2 ou meshy-t2.5 que não defina ai_model. Com ai_model: meshy-n1, true devolve 400.

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

Valores disponíveis:

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

Resoluções mais altas captam mais detalhe de superfície. 4k e 8k requerem ai_model meshy-6, meshy-7.1 ou latest. Com meshy-n1, devolvem 400. Em 8k, a Meshy não gera mapa de emissão.

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

Texto que orienta a texturização, até 800 caracteres. Texto mais longo devolve 400. Envie texture_prompt ou texture_image_url, não ambos. Se enviar ambos, a Meshy usa texture_prompt. Com ai_model: meshy-n1, enviá-lo devolve 400.

Uma imagem 2D que orienta a texturização, como um URL público ou um Data URI codificado em base64, como data:image/jpeg;base64,<os seus dados de imagem codificados em base64>.

A imagem tem de ser um ficheiro .jpg, .jpeg, .png ou .webp de, no máximo, 20 MB, pelo menos 32 pixels em cada lado e, no máximo, 178 956 970 pixels (largura × altura).

Com ai_model: meshy-n1, a Meshy texturiza a partir desta imagem como vista frontal.

O modelo de IA que texturiza a malha.

Valores disponíveis:

• meshy-6-lite
• meshy-6
• meshy-7.1
• latest: Meshy 7.1
• meshy-n1: uma textura de cor base em 2K apenas a partir de uma imagem de referência. Sem prompt de texto, sem mapas PBR, sem 4K ou 8K.
• meshy-7 (obsoleto): envie meshy-7.1 em vez disto

Omita para usar o modelo da tarefa de preview, de forma a que o preview e o seu refine corram no mesmo modelo do início ao fim. Envie um valor para o substituir. Um latest explícito resolve-se da mesma forma que na tarefa de preview, pelo que um preview latest e o seu refine latest usam sempre o mesmo modelo de textura.

Com meshy-n1, a Meshy texturiza a partir de texture_image_url. Sem ele, a Meshy usa a imagem de referência que um preview meshy-7.1 ou latest armazena. Qualquer outro preview devolve 400 a menos que envie texture_image_url. O preview pode ter, no máximo, 7 999 999 triângulos. Um preview remeshed para quads devolve 400.

Se deve verificar texture_prompt e texture_image_url em busca de conteúdo prejudicial antes de gerar. Se a Meshy detetar conteúdo prejudicial, o pedido devolve 400 e a 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-no e ignoram-no, assim como um refine de um preview meshy-t2 ou meshy-t2.5 que não defina ai_model. Enviá-lo com meshy-6-lite devolve 400. Com meshy-n1, true devolve 400.

Os formatos de ficheiro a gerar. A Meshy gera e devolve apenas estes formatos, o que pode encurtar a tarefa. Se o omitir, a Meshy gera todos os formatos exceto 3mf, que só gera quando o solicita.

Valores disponíveis:

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

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

Se deve estimar a altura real do objeto com visão de IA e redimensionar o modelo em conformidade. A Meshy coloca a origem na base, a menos que defina origin_at.

O pedido não pode ser executado. A mensagem de erro indica qual o problema encontrado. Por exemplo:

• ID de tarefa inválido: preview_task_id é inválido, ou não corresponde a nenhuma das suas tarefas de preview.
• Tarefa não pronta: A tarefa de preview ainda não foi concluída com sucesso.
• Incompatibilidade de modelo: O modelo de IA da tarefa de preview não funciona com o modelo de refine solicitado.
• Modelo não suportado para remove_lighting: remove_lighting foi enviado com ai_model: "meshy-6-lite".
• Sem imagem de referência para o Meshy N1: ai_model: meshy-n1 foi enviado sem texture_image_url, e o preview não tem nenhuma imagem de referência que o Meshy N1 possa usar. Envie texture_image_url.
• Preview em quads para o Meshy N1: ai_model: meshy-n1 foi enviado para um preview remeshed para quads. Faça o refine com outro ai_model.
• Demasiados triângulos para o Meshy N1: Com ai_model: meshy-n1, o preview tem mais de 7 999 999 triângulos. Faça o refine com outro ai_model.
• Opção não suportada para o Meshy N1: ai_model: meshy-n1 foi enviado com uma destas opções:
  • texture_prompt
  • enable_pbr: true
  • texture_resolution de 4k ou 8k
  • hd_texture: true sem texture_resolution
  • remove_lighting: true

Corrija o pedido e envie-o novamente. Consulte Erros.

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

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 o seu saldo de créditos e tente novamente.
• Plano gratuito: Criar uma tarefa requer um plano pago. Atualize o seu plano nas definições de subscrição e tente novamente.

A moderação de conteúdo bloqueou o prompt ou uma imagem de entrada. Altere a entrada e tente novamente.

Excedeu o seu limite de taxa. Aguarde e tente novamente. Consulte Limites de taxa.

O ID da tarefa proveniente da resposta de criação.

O ID da tarefa a eliminar.

O número da página a devolver, até 255. Um valor superior devolve 400.

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

A ordem de ordenação.

Valores disponíveis:

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

O ID da tarefa proveniente da resposta de criação.

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

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

URLs de transferência para o modelo 3D gerado, um por formato de ficheiro. Um formato que a tarefa não gerou não tem chave, em vez de uma string vazia.

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

O prompt de texto que enviou para orientar a texturização na fase de refine.

Consulte geometry_resolution em vez disto.

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

URL de transferência para a imagem que enviou para orientar a texturização.

URL de transferência para uma imagem de miniatura do modelo 3D.

URL de transferência para uma versão de thumbnail_url com fundo transparente (RGBA). Presente apenas quando criou a tarefa com alpha_thumbnail: true e a Meshy renderizou a pré-visualização transparente.

Quanto da tarefa está concluído, em percentagem. É 0 até a tarefa começar e 100 quando é bem-sucedida.

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

Hora a que a tarefa foi criada, em milissegundos Unix.

Hora a que a tarefa terminou, em milissegundos Unix. É 0 até a tarefa terminar.

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

URLs de transferência para os mapas de textura gerados, como um array de objetos. Normalmente contém um objeto. Cada objeto tem estes campos:

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

Os detalhes do erro quando a tarefa falha. É null a menos que o estado seja FAILED. Consulte Erros.

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