lowpoly será descontinuado em 30 de out. de 2026. meshy-7 como modelo de geração 3D será descontinuado em 31 de dez. de 2026; como modelo de textura continua disponível. Troque de modelo antes dessas datas para evitar erros nas solicitações. Ver todas as descontinuações

API de Texto para 3D

Gere modelos 3D a partir de prompts de texto em sua própria aplicação.

O Texto para 3D funciona em duas etapas. Primeiro, crie uma tarefa de preview (mode: "preview") para gerar uma malha 3D sem textura, para que você possa verificar o formato. Em seguida, envie o ID da tarefa de preview bem-sucedida para uma tarefa de refine (mode: "refine") para texturizar a malha. Ambas as etapas usam o mesmo endpoint.


POST/openapi/v2/text-to-3d

Create a Text to 3D preview task

Cria uma tarefa de preview de Texto para 3D, que gera uma malha 3D sem textura (apenas geometria) a partir de um prompt de texto. Essa é a primeira etapa do fluxo de trabalho de duas etapas. Após o preview ser concluído com sucesso, envie o ID dessa tarefa em uma tarefa de refine para texturizar a malha. Veja Criar uma tarefa de refine de Texto para 3D. Para o esquema completo da resposta, veja O objeto de tarefa de Texto para 3D.

A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa geralmente leva, veja Tempos de processamento.

Request

POST
/openapi/v2/text-to-3d
# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with Ultra 4K geometry, remesh, and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Parâmetros

  • Name
    mode
    Type
    string
    Obrigatório
    Description

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

  • Name
    prompt
    Type
    string
    Obrigatório
    Description

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

  • Name
    model_type
    Type
    string
    padrão standard
    Description

    O tipo de malha 3D a ser gerada.

    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, o Meshy ignora should_remesh e decimation_mode, e aceita apenas topology: 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 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. Ele será descontinuado em 31 de dezembro de 2026.

    Modelos Smart Topology (model_type: smart-topology):

    • meshy-t2: topology mais limpa, partes nativamente separadas, 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

    Veja Modelos para saber qual modelo se encaixa no seu projeto, como um personagem de jogo ou uma impressão 3D.

  • Name
    geometry_resolution
    Type
    string
    padrão standard
    Description

    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 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 retornam 400.

  • Name
    ultra_mode
    Type
    boolean
    ⚠ obsoleto
    padrão false
    Description

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

  • Name
    should_remesh
    Type
    boolean
    padrão true (meshy-6-lite), false (other models)
    Description

    Se deve refazer a malha do modelo após a geração. Para o modelo 3D de mais alta qualidade, envie false.

Aplica-se somente quando should_remesh = true
  • Name
    topology
    Type
    string
    padrão triangle
    Description

    O tipo de face do modelo com malha refeita.

    Valores disponíveis:

    • quad: uma malha predominantemente quad
    • triangle: uma malha de triângulos decimada

    A saída do Smart Topology é apenas em triângulos. Enviar quad com ai_model meshy-t2 ou meshy-t2.5 retorna 400.

  • Name
    decimation_mode
    Type
    integer
    Description

    Contagem de faces adaptativa, por nível. Quando você define isso, o Meshy ignora target_polycount.

    Valores disponíveis:

    • 1: ultra
    • 2: alto
    • 3: médio
    • 4: baixo
  • Name
    target_polycount
    Type
    integer
    Description

    O número de faces desejado. O resultado pode diferir do alvo, dependendo da geometria. Isso se aplica em dois casos separados:

    • Remesh: com should_remesh: true em um modelo standard. O Meshy refaz a malha (decima) para cerca dessa contagem. Se você definir decimation_mode, o Meshy o utiliza 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:

    CasoIntervaloPadrão
    Remesh100 a 30000030000
    meshy-t2100 a 150004000
    meshy-t2.5100 a 3000015000

    Um valor fora do intervalo retorna 400.

    Para um asset de jogo low-poly, use um modelo Smart Topology em vez de refazer a malha de um modelo standard. Veja Modelos.

  • Name
    symmetry_mode
    Type
    string
    ⚠ obsoleto
    padrão auto
    Description

    Não inclua. 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: impõe simetria durante a geração
  • Name
    pose_mode
    Type
    string
    Description

    A pose para um modelo de personagem, a-pose ou t-pose. Para não ter pose nenhuma, não inclua pose_mode nem is_a_t_pose.

  • Name
    is_a_t_pose
    Type
    boolean
    ⚠ obsoleto
    padrão false
    Description

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

  • Name
    art_style
    Type
    string
    ⚠ obsoleto
    padrão realistic
    Description

    Não inclua. O Meshy o ignora.

  • Name
    moderation
    Type
    boolean
    padrão false
    Description

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

  • Name
    target_formats
    Type
    string[]
    Description

    Os formatos de arquivo a serem gerados. O Meshy gera e retorna apenas esses formatos, o que pode encurtar a tarefa. Se você não incluir isso, o Meshy gera todos os formatos, exceto 3mf, que ele gera apenas quando solicitado.

    Valores disponíveis:

    • glb
    • obj
    • fbx
    • stl
    • usdz
    • 3mf
  • Name
    alpha_thumbnail
    Type
    boolean
    padrão false
    Description

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

  • Name
    auto_size
    Type
    boolean
    padrão false
    Description

    Se deve estimar a altura real do objeto usando visão computacional de IA e redimensionar o modelo de acordo. O Meshy coloca a origem na parte inferior, a menos que você defina origin_at.

Aplica-se somente quando auto_size = true
  • Name
    origin_at
    Type
    string
    padrão bottom
    Description

    Onde colocar a origem do modelo, bottom ou center.

Retornos

O campo result da resposta contém o ID da nova tarefa de Texto para 3D.

Modos de falha

  • Name
    400 - Bad Request
    Description

    A requisição não pode ser executada. A mensagem de erro indica 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 pode executá-lo.

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

  • 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 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.
  • 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
    429 - Too Many Requests
    Description

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


POST/openapi/v2/text-to-3d

Criar uma tarefa de refine do Texto para 3D

Cria uma tarefa de refine do Texto para 3D, que texturiza a malha de uma tarefa de preview concluída. Envie o ID de uma tarefa de preview bem-sucedida como preview_task_id. Veja Criar uma tarefa de preview do Texto para 3D. Esta é a segunda etapa do fluxo de trabalho de duas etapas.

A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa costuma levar, veja Tempos de processamento.

Request

POST
/openapi/v2/text-to-3d
# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

# Refine with Meshy N1 from the preview's stored reference image
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "ai_model": "meshy-n1"
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Parâmetros

  • Name
    mode
    Type
    string
    Obrigatório
    Description

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

  • Name
    preview_task_id
    Type
    string
    Obrigatório
    Description

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

  • Name
    enable_pbr
    Type
    boolean
    padrão false
    Description

    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 e latest não geram um mapa de emissão. O mesmo vale para um refine de um preview meshy-t2 ou meshy-t2.5 que não defina ai_model. Com ai_model: meshy-n1, true retorna 400.

  • Name
    texture_resolution
    Type
    string
    padrão 2k
    Description

    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 ou latest. Com meshy-n1, retornam 400. Em 8k, o Meshy não gera um mapa de emissão.

  • Name
    hd_texture
    Type
    boolean
    ⚠ obsoleto
    padrão false
    Description

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

  • Name
    texture_prompt
    Type
    string
    Description

    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. Com ai_model: meshy-n1, enviá-lo retorna 400.

  • Name
    texture_image_url
    Type
    string
    Description

    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, com pelo menos 32 pixels em cada lado e no máximo 178.956.970 pixels (largura × altura).

    Com ai_model: meshy-n1, o Meshy texturiza a partir dessa imagem como a visão frontal.

  • Name
    ai_model
    Type
    string
    padrão inherited from the preview task
    Description

    O modelo de IA que texturiza a malha. A malha vem do preview, então, em um refine, ai_model escolhe apenas o modelo de textura.

    Valores disponíveis:

    • meshy-7: Meshy 7
    • latest: o modelo de textura mais recente, atualmente o Meshy 7
    • meshy-6: Meshy 6
    • meshy-6-lite: Meshy 6 Lite
    • meshy-n1: uma textura de cor base em 2K a partir apenas de uma imagem de referência. Sem prompt de texto, sem mapas PBR, sem 4K ou 8K.

    Os valores acima são modelos de textura. Omita para texturizar com o modelo que corresponde ao preview. Envie um valor para substituí-lo.

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

  • Name
    moderation
    Type
    boolean
    padrão false
    Description

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

  • 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 iluminação personalizada.

    Tem efeito apenas quando ai_model é meshy-6. meshy-7 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 defina ai_model. Enviá-lo com meshy-6-lite retorna 400. Com meshy-n1, true retorna 400.

  • Name
    target_formats
    Type
    string[]
    Description

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

    Valores disponíveis:

    • glb
    • obj
    • fbx
    • stl
    • usdz
    • 3mf
  • Name
    alpha_thumbnail
    Type
    boolean
    padrão false
    Description

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

  • Name
    auto_size
    Type
    boolean
    padrão false
    Description

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

Aplica-se somente quando auto_size = true
  • Name
    origin_at
    Type
    string
    padrão bottom
    Description

    Onde colocar a origem do modelo, bottom ou center.

Retornos

O campo result da resposta contém o ID da nova tarefa de Texto 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:

    • ID de tarefa inválido: preview_task_id é inválido ou não corresponde a nenhuma de suas tarefas de preview.
    • Tarefa não está 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".
    • Nenhuma imagem de referência para o Meshy N1: ai_model: meshy-n1 foi enviado sem texture_image_url, e o preview não possui 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 remesh para quads. Faça o refine com outro ai_model.
    • Triângulos demais 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 a solicitação e envie-a novamente. Veja Erros.

  • 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
    429 - Too Many Requests
    Description

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


GET/openapi/v2/text-to-3d/:id

Obter uma tarefa de Texto para 3D

Retorna uma tarefa de Texto para 3D pelo seu ID. Funciona tanto para tarefas de preview quanto de refine.

Request

GET
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?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=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 20
}

Parâmetros

  • Name
    id
    Type
    path
    Description

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

Retornos

O objeto de tarefa de Texto para 3D.

Exemplos

A tabela a seguir mostra um modelo de exemplo para cada mode.

ModeModelo de exemplo
PreviewPreview model
RefineRefined model

DELETE/openapi/v2/text-to-3d/:id

Excluir uma tarefa de Texto para 3D

Exclui permanentemente uma tarefa de Texto para 3D, incluindo seus modelos e dados. Você não pode desfazer uma exclusão.

Request

DELETE
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-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 na sua criação.

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 alcance o status SUCCEEDED, FAILED ou CANCELED para então excluí-la.

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.


GET/openapi/v2/text-to-3d

Listar tarefas de Texto para 3D

Retorna uma lista das suas tarefas de Texto para 3D.

Request

GET
/openapi/v2/text-to-3d
curl https://api.meshy.ai/openapi/v2/text-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "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=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": null,

    "consumed_credits": 20
  }
]

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 retorna 400.

  • 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

Retornos

Uma lista paginada de objetos de tarefa de Texto para 3D.


GET/openapi/v2/text-to-3d/:id/stream

Transmitir uma tarefa de Texto para 3D em stream

Transmite as atualizações de uma tarefa de Texto para 3D como Server-Sent Events (SSE).

Request

GET
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v2/text-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",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"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": 20
}

Parâmetros

  • Name
    id
    Type
    path
    Description

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

Retornos

Um stream de objetos de tarefa de Texto 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 Texto para 3D

Um objeto de tarefa Texto para 3D descreve uma tarefa que gera um modelo 3D a partir de um prompt de texto. Ele contém o status, o progress e os arquivos do modelo quando a tarefa é concluída com sucesso. Texto para 3D tem dois estágios, preview e refine. Uma tarefa de preview gera um modelo 3D apenas com malha, e uma tarefa de refine gera um modelo 3D texturizado a partir do resultado do preview.

Propriedades

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "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": 20
}
  • 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, text-to-3d-preview para uma tarefa de preview ou text-to-3d-refine para uma tarefa de refine.

  • 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
      usdz
      Type
      string
      Description

      O arquivo USDZ.

    • Name
      obj
      Type
      string
      Description

      O arquivo OBJ.

    • Name
      mtl
      Type
      string
      Description

      O arquivo MTL.

    • Name
      stl
      Type
      string
      Description

      O arquivo STL.

    • Name
      3mf
      Type
      string
      Description

      O arquivo 3MF. Presente apenas quando target_formats inclui 3mf.

  • Name
    prompt
    Type
    string
    Description

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

  • Name
    texture_prompt
    Type
    string
    Description

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

  • Name
    ultra_mode
    Type
    boolean
    ⚠ obsoleto
    Description

    Use geometry_resolution em vez disso.

  • Name
    geometry_resolution
    Type
    string
    Description

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

  • Name
    texture_image_url
    Type
    string
    Description

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

  • Name
    thumbnail_url
    Type
    string
    Description

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

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

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

  • Name
    progress
    Type
    integer
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    status
    Type
    string
    Description

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

  • Name
    texture_urls
    Type
    array
    Description

    URLs de download para os mapas de textura gerados, 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. Ausente quando você criou a tarefa com enable_pbr: false.

    • Name
      normal
      Type
      string
      Description

      O mapa de normais. Ausente quando você criou a tarefa com enable_pbr: false.

    • Name
      roughness
      Type
      string
      Description

      O mapa de rugosidade. Ausente quando você criou a tarefa com enable_pbr: false.

    • Name
      emission
      Type
      string
      Description

      O mapa de emissão. Ausente em qualquer um destes casos:

      • Você criou a tarefa com enable_pbr: false.
      • ai_model é meshy-6-lite, meshy-7, meshy-7.1, ou latest.
      • texture_resolution é 8k.
      • A tarefa refina um preview meshy-t2 ou meshy-t2.5 sem definir ai_model.
  • Name
    preceding_tasks
    Type
    integer
    Description

    O número de tarefas à frente desta na fila. O valor só é significativo 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 seja FAILED. Veja Erros.

  • Name
    consumed_credits
    Type
    integer
    Description

    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.