API de Imagem para 3D

A API de Imagem para 3D é uma funcionalidade que permite integrar as capacidades de Imagem para 3D da Meshy na sua própria aplicação. Nesta secção, encontrará toda a informação necessária para começar a utilizar esta API.

POST/openapi/v1/image-to-3d

Criar uma Tarefa de Imagem para 3D

Este endpoint permite-lhe criar uma nova tarefa de Imagem para 3D. Consulte o O Objeto de Tarefa de Imagem para 3D para ver quais propriedades estão incluídas com o objeto de tarefa de Imagem para 3D.

Parâmetros

Apenas um de input_task_id ou image_url é necessário. Se ambos forem fornecidos, input_task_id tem prioridade.

Name
input_task_id
Type
string
Obrigatório
Description
O ID de uma tarefa de geração de imagem concluída cujo resultado deve ser utilizado como a imagem de entrada. Esta tarefa deve ser uma das seguintes: Texto para Imagem ou Imagem para Imagem. Além disso, deve ter sido executada através da API, ter um estado de SUCCEEDED, e produzir exatamente uma imagem.

Name
image_url
Type
string
Obrigatório
Description
Forneça uma imagem para a Meshy usar na criação do modelo. Atualmente, suportamos os formatos .jpg, .jpeg, e .png.
Existem duas maneiras de fornecer a imagem:
- URL publicamente acessível: Um URL acessível pela internet pública.
- Data URI: Um Data URI codificado em base64 da imagem. Exemplo de um Data URI: data:image/jpeg;base64,<seus dados de imagem codificados em base64>.

Name
model_type
Type
string
predefinição standard
Description
Especificar o tipo de geração de malha 3D.
Valores disponíveis:
- standard: Geração de malha 3D regular de alto detalhe.
- smart-topology: Escolha um modelo Smart Topology com ai_model (meshy-t1 ou meshy-t2).
- lowpoly (obsoleto): Gera uma malha low-poly otimizada para polígonos mais limpos. Recomendamos usar smart-topology em vez.
Quando smart-topology é selecionado, topology, should_remesh, e save_pre_remeshed_model são ignorados.
Quando lowpoly é selecionado, ai_model, topology, target_polycount, should_remesh, e save_pre_remeshed_model são ignorados.
Name
ai_model
Type
string
predefinição latest
Description
ID do modelo a usar. Os valores disponíveis dependem de model_type.
Geração standard (model_type: standard):
- meshy-5, meshy-6, meshy-7, latest (Meshy 7)
Geração Smart Topology (model_type: smart-topology):
- meshy-t2 (default, recomendado): o modelo Smart Topology — topologia mais limpa, partes separadas nativamente, saída em triângulo e uma contagem de faces que pode ser definida com target_polycount.
- meshy-t1: o antigo modelo low-poly; não suporta a definição de uma contagem de faces com target_polycount.
Name
ultra_mode
Type
boolean
predefinição false
Description
Ativa a geração Ultra para uma geometria de maior fidelidade com detalhes de superfície mais finos.
Apenas suportado quando ai_model é meshy-7 (ou latest).
Name
should_texture
Type
boolean
predefinição true
Description
Determina se as texturas são geradas. Definir para false ignora a fase de textura, fornecendo uma malha sem texturas.

Aplica-se apenas quando should_texture = true

Name
enable_pbr
Type
boolean
predefinição false
Description
Gerar Mapas PBR (metálico, rugosidade, normal) além da cor base. Um mapa de emissão também é incluído quando ai_model é meshy-6, exceto em texture_resolution: 8k. meshy-7 e latest não produzem um mapa de emissão.
Name
texture_resolution
Type
string
predefinição 2k
Description
Resolução da textura de cor base. Um de 2k (2048×2048), 4k (4096×4096), ou 8k (8192×8192). Resoluções mais altas capturam mais detalhes de superfície.
4k e 8k não estão disponíveis com ai_model: meshy-5. Em 8k, nenhum mapa de emissão é produzido.
Name
hd_texture
Type
boolean
⚠ obsoleto
predefinição false
Description
Use texture_resolution em vez — equivalente a texture_resolution: "4k". Quando ambos estiverem definidos, texture_resolution tem precedência.
Name
texture_prompt
Type
string
Description
Forneça um prompt de texto para guiar o processo de texturização. Máximo de 600 caracteres.
Name
texture_image_url
Type
string
Description
Forneça uma imagem 2D para guiar o processo de texturização. Atualmente, suportamos os formatos .jpg, .jpeg, e .png.
Existem duas maneiras de fornecer a imagem:
- URL publicamente acessível: Um URL acessível pela internet pública.
- Data URI: Um Data URI codificado em base64 da imagem. Exemplo de um Data URI: data:image/jpeg;base64,<seus dados de imagem codificados em base64>.
A texturização de imagem pode não funcionar de forma otimizada se houver diferenças substanciais de geometria entre o asset original e a imagem carregada. Apenas um de texture_image_url ou texture_prompt pode ser usado para guiar o processo de texturização. Se ambos os parâmetros forem fornecidos, então texture_prompt será utilizado para texturizar o modelo por padrão. A texturização via texto ou imagem custará 10 créditos por tarefa.

Name
should_remesh
Type
boolean
predefinição false (meshy-6, meshy-7), true (others)
Description
Controla se deve ativar a fase de remesh. Para o modelo de maior qualidade, recomendamos definir should_remesh para false.

Aplica-se apenas quando should_remesh = true

Name
topology
Type
string
predefinição triangle
Description
Especificar a topology do modelo gerado.
Valores disponíveis:
- quad: Gera uma malha dominante em quadrado.
- triangle: Gera uma malha de triângulos decimada.
Name
decimation_mode
Type
integer
Description
Ative a decimação adaptativa definindo um nível de contagem de polígonos. Quando configurado, target_polycount é ignorado.
Valores disponíveis:
- 1: Adaptativo — contagem de polígonos ultra.
- 2: Adaptativo — contagem de polígonos alta.
- 3: Adaptativo — contagem de polígonos média.
- 4: Adaptativo — contagem de polígonos baixa.
Name
save_pre_remeshed_model
Type
boolean
predefinição false
Description
Quando definido como true, o Meshy também armazena um arquivo GLB extra antes da fase de remesh ser concluída.

Name
target_polycount
Type
integer
Description
Número-alvo de polígonos (faces) na saída. A contagem real pode desviar do alvo dependendo da geometria.
target_polycount faz efeito em dois casos independentes:
- Remesh — com should_remesh: true num modelo standard. A malha é remeshed (decimada) aproximadamente para esta contagem. Intervalo de 100 a 300.000, padrão de 30.000. Se decimation_mode estiver configurado, ele 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; nenhum remesh é executado e should_remesh não é necessário. Intervalo de 100 a 15.000, padrão de 4.000.

Name
symmetry_mode
Type
string
⚠ obsoleto
predefinição auto
Description
Obsoleto. Este parâmetro não afeta mais a saída.
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 simetria durante a geração.
Name
pose_mode
Type
string
predefinição ""
Description
Especifica o modo de pose para o modelo gerado.
Valores disponíveis:
- a-pose: Gera o modelo em uma pose A.
- t-pose: Gera o modelo em uma pose T.
- "" (string vazia): Nenhuma pose específica aplicada.
Name
is_a_t_pose
Type
boolean
⚠ obsoleto
predefinição false
Description
Use pose_mode em vez disso. Se gerar o modelo em uma pose A/T.
Name
image_enhancement
Type
boolean
predefinição true
Description
Otimiza a imagem de entrada para melhores resultados. Defina como false para preservar a aparência exata da imagem de entrada sem qualquer processamento de estilo.
Apenas suportado quando ai_model é meshy-6, meshy-7, ou latest.
Name
remove_lighting
Type
boolean
predefinição true
Description
Remove destaques e sombras da textura de cor base, produzindo um resultado mais limpo que funciona melhor em configurações de iluminação personalizadas.
Apenas suportado quando ai_model é meshy-6.
Name
moderation
Type
boolean
predefinição false
Description
Quando definido como true, o conteúdo de entrada será automaticamente verificado por conteúdo potencialmente prejudicial. Se for detectado conteúdo prejudicial, a tarefa não prosseguirá para a geração.
O conteúdo dos inputs image_url, texture_image_url, e texture_prompt será verificado.
Name
target_formats
Type
string[]
Description
Especifica quais formatos de arquivo 3D incluir na saída. Apenas os formatos solicitados serão gerados e retornados, 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 omitido, todos os formatos, exceto 3mf, são gerados. 3mf só é incluído quando explicitamente especificado.
Name
auto_size
Type
boolean
predefinição false
Description
Quando configurado como true, o serviço usa visão de IA para estimar automaticamente a altura real do objeto e redimensionar o modelo de acordo. A origem será padrão para bottom, a menos que origin_at seja explicitamente definido.
Name
alpha_thumbnail
Type
boolean
predefinição false
Description
Quando definido como true, a tarefa também renderiza uma versão com fundo transparente (RGBA) do preview e a retorna como alpha_thumbnail_url na resposta GET. O campo thumbnail_url existente permanece inalterado.
Name
multi_view_thumbnails
Type
boolean
predefinição false
Description
Quando definido como true, a tarefa também renderiza quatro miniaturas com visualizações cardeais (frontal, direita, traseira, esquerda) e as retorna sob thumbnail_urls na resposta GET. O campo thumbnail_url existente permanece inalterado e continua a apontar para a visualização frontal, então os clientes existentes são mantidos.
Adiciona aproximadamente 3 segundos à latência da tarefa.

Aplica-se apenas quando auto_size = true

Name
origin_at
Type
string
predefinição bottom
Description
Posição da origem quando auto_size está ativado.
Valores disponíveis: bottom, center.

Retornos

A propriedade result da resposta contém o id da tarefa recém-criada de Imagem para 3D.

Modos de Falha

Name
400 - Bad Request
Description
A requisição era inaceitável. Causas comuns:
- Parâmetro em falta: Ou image_url ou input_task_id deve ser fornecido.
- Tarefa de entrada inválida: O input_task_id deve referir-se a uma tarefa de Texto para Imagem ou Imagem para Imagem que produza exatamente uma imagem.
- Formato de imagem inválido: O image_url fornecido não é um formato suportado (.jpg, .jpeg, .png).
- URL inacessível: O image_url não pôde ser baixado (404 ou timeout).
- Data URI inválido: A string base64 está malformada.
- Combinação de parâmetros inválida: enable_pbr é suportado apenas quando should_texture é verdadeiro.
Name
401 - Unauthorized
Description
Falha na autenticação. Por favor, verifique a sua chave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarefa.
Name
429 - Too Many Requests
Description
Excedeu o seu limite de taxa.

Request

POST

/openapi/v1/image-to-3d

# Solicitação simples com os parâmetros obrigatórios
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": "<seu URL de imagem publicamente acessível ou Data URI codificado em base64>"
  }'

# Com remesh, PBR, e 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": "<seu URL de imagem publicamente acessível ou Data URI codificado em base64>",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

Response

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

GET/openapi/v1/image-to-3d/:id

Obter uma Tarefa de Imagem para 3D

Este endpoint permite-lhe obter uma tarefa de Imagem para 3D dado um id de tarefa válido. Consulte o O Objeto de Tarefa de Imagem para 3D para ver quais propriedades estão incluídas com o objeto de tarefa de Imagem para 3D.

Parâmetros

Name
id
Type
path
Description
Identificador único para a tarefa de Imagem para 3D a obter.

Retornos

A resposta contém o objeto de tarefa de Imagem para 3D. Verifique a secção O Objeto de Tarefa de Imagem para 3D para detalhes.

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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": {
    "message": ""
  },
  "consumed_credits": 30
}

DELETE/openapi/v1/image-to-3d/:id

Eliminar uma Tarefa de Imagem para 3D

Este endpoint elimina permanentemente uma tarefa de Imagem para 3D, incluindo todos os modelos e dados associados. Esta ação é irreversível.

Parâmetros de Caminho

Name
id
Type
path
Description
O ID da tarefa de Imagem para 3D a eliminar.

Retornos

Retorna 200 OK com sucesso.

Request

DELETE

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

// Retorna 200 Ok com sucesso.

GET/openapi/v1/image-to-3d

Listar Tarefas de Imagem para 3D

Este endpoint permite-lhe obter uma lista de tarefas de Imagem para 3D.

Parâmetros

Atributos opcionais

Name
page_num
Type
integer
Description
Número da página para paginação. Começa e por padrão é 1.
Name
page_size
Type
integer
Description
Limite de tamanho da página. Por padrão, é 10 itens. O máximo permitido é 50 itens.
Name
sort_by
Type
string
Description
Campo para ordenar por. Valores disponíveis:
- +created_at: Ordenar por tempo de criação em ordem ascendente.
- -created_at: Ordenar por tempo de criação em ordem descendente.

Retornos

Retorna uma lista paginada de Os Objetos de Tarefa de Imagem para 3D.

Request

GET

/openapi/v1/image-to-3d

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": {
      "message": ""
    },
    "consumed_credits": 30
  }
]

GET/openapi/v1/image-to-3d/:id/stream

Transmitir uma Tarefa de Imagem para 3D

Este endpoint transmite atualizações em tempo real para uma tarefa de Imagem para 3D usando Eventos Enviados pelo Servidor (SSE).

Parâmetros

Name
id
Type
path
Description
Identificador único para transmitir a tarefa de Imagem para 3D.

Retornos

Retorna um fluxo de Os Objetos de Tarefa de Imagem para 3D como Eventos Enviados pelo Servidor.

Para tarefas PENDING ou IN_PROGRESS, o fluxo de resposta incluirá apenas os campos necessários de progress e status.

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

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

// Exemplo de evento de erro
event: error
data: {
  "status_code": 404,
  "message": "Tarefa não encontrada"
}

// Exemplos de eventos de mensagem ilustram o progresso da tarefa.
// Para tarefas PENDING ou IN_PROGRESS, o fluxo de resposta não incluirá todos os campos.
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": {
    "message": ""
  },
  "consumed_credits": 30
}

O Objeto de Tarefa de Imagem para 3D

O objeto de Tarefa de Imagem para 3D é uma unidade de trabalho que a Meshy rastreia para gerar um modelo 3D a partir de uma imagem de entrada. O objeto tem as seguintes propriedades:

Propriedades

Name
id
Type
string
Description
Identificador único para a tarefa. Embora usemos um UUID k-sortável para ids de tarefas como detalhe de implementação, você deve não fazer quaisquer suposições sobre o formato do id.
Name
type
Type
string
Description
Tipo da tarefa de Imagem para 3D. O valor é image-to-3d.
Name
model_urls
Type
object
Description
URL para download do arquivo de modelo 3D texturizado gerado pela Meshy. A propriedade para um formato será omitida se o formato não for gerado em vez de retornar uma string vazia.
- Name
  glb
  Type
  string
  Description
  URL para download do arquivo GLB.
- Name
  fbx
  Type
  string
  Description
  URL para download do arquivo FBX.
- Name
  obj
  Type
  string
  Description
  URL para download do arquivo OBJ.
- Name
  usdz
  Type
  string
  Description
  URL para download do arquivo USDZ.
- Name
  mtl
  Type
  string
  Description
  URL para download do arquivo MTL, retornado junto com exportações OBJ quando as texturas estão presentes.
- Name
  stl
  Type
  string
  Description
  URL para download do arquivo STL.
- Name
  3mf
  Type
  string
  Description
  URL para download do arquivo 3MF. Apenas presente quando 3mf foi solicitado via target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  URL para download da saída original GLB antes do remeshing.
  Disponível apenas quando a tarefa foi criada com ambos should_remesh: true e save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
URL para download da imagem miniatura do arquivo do modelo. Equivalente a thumbnail_urls.front quando presente, mantido para compatibilidade retroativa.
Name
alpha_thumbnail_url
Type
string
Description
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.
Name
thumbnail_urls
Type
object
Description
URLs para download de quatro miniaturas com visualizações cardeais do modelo 3D gerado. Cada valor é uma URL assinada para uma PNG 512×512 renderizada com os mesmos materiais e iluminação que thumbnail_url. Útil para pré-visualizar o modelo a partir de múltiplos ângulos em pipelines em lote sem baixar o GLB.
Apenas presente quando a tarefa foi criada com multi_view_thumbnails: true e alcançou SUCCEEDED. Tarefas mais antigas e tarefas criadas sem essa opção não incluirão este campo.
- Name
  front
  Type
  string
  Description
  Vista frontal, 0° de rotação em torno do eixo vertical (corresponde a thumbnail_url).
- Name
  right
  Type
  string
  Description
  Vista direita, 90° de rotação.
- Name
  back
  Type
  string
  Description
  Vista traseira, 180° de rotação.
- Name
  left
  Type
  string
  Description
  Vista esquerda, 270° de rotação.
Name
texture_prompt
Type
string
Description
O prompt de texto que foi usado para guiar o processo de texturização.
Name
texture_image_url
Type
string
Description
URL para download da imagem de textura que foi usada para guiar o processo de texturização.
Name
ultra_mode
Type
boolean
Description
Reflete o valor de ultra_mode com que a tarefa foi criada. Apenas presente para tarefas meshy-7 (ou latest) que definiram explicitamente ultra_mode; omitido caso contrário.
Name
progress
Type
integer
Description
Progresso da tarefa. Se a tarefa ainda não foi iniciada, esta propriedade será 0. Uma vez que a tarefa tenha sucesso, isso se tornará 100.
Name
started_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi iniciada, em milissegundos. Se a tarefa ainda não foi iniciada, esta propriedade será 0.
Um carimbo de data/hora representa o número de milissegundos decorridos desde 1 de janeiro de 1970 UTC, seguindo o padrão RFC 3339. Por exemplo, sexta-feira, 1 de setembro de 2023 12:00:00 PM GMT é representado como 1693569600000. Isso se aplica a todos os carimbos de data/hora na Meshy API.
Name
created_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi criada, em milissegundos.
Name
expires_at
Type
timestamp
Description
Carimbo de data/hora de quando o resultado da tarefa expira, em milissegundos.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi concluída, em milissegundos. Se a tarefa ainda não foi concluída, esta propriedade será 0.
Name
status
Type
string
Description
Status da tarefa. Valores possíveis são um de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Um array de objetos de URL de textura que são gerados a partir da tarefa. Normalmente, isso contém apenas um objeto de URL de textura. Cada URL de textura tem as seguintes propriedades:
- Name
  base_color
  Type
  string
  Description
  URL para download do mapa de cor base.
- Name
  metallic
  Type
  string
  Description
  URL para download do mapa metálico.
  Se a tarefa for criada com enable_pbr: false, esta propriedade será omitida.
- Name
  normal
  Type
  string
  Description
  URL para download do mapa de normais.
  Se a tarefa for criada com enable_pbr: false, esta propriedade será omitida.
- Name
  roughness
  Type
  string
  Description
  URL para download do mapa de rugosidade.
  Se a tarefa for criada com enable_pbr: false, esta propriedade será omitida.
- Name
  emission
  Type
  string
  Description
  URL para download do mapa de emissão.
  Se a tarefa for criada com enable_pbr: false, ou ai_model for meshy-5, meshy-7, ou latest, esta propriedade será omitida.
Name
preceding_tasks
Type
integer
Description
A contagem de tarefas anteriores.
O valor deste campo é significativo apenas se o status da tarefa for PENDING.
Name
task_error
Type
object
Description
Detalhes de erro para tarefas falhadas. Veja Erros para a referência completa do objeto task_error.
Name
consumed_credits
Type
integer
Description
O número de créditos consumidos por esta tarefa. Presente quando o status da tarefa é PENDING, IN_PROGRESS, ou SUCCEEDED. Retorna 0 para tarefas FAILED (créditos são reembolsados em caso de falha).

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": {
    "message": ""
  },
  "consumed_credits": 30
}