API de Multi-imagem para 3D

A API de Multi-imagem para 3D é um recurso que permite integrar as capacidades de Multi-imagem para 3D da Meshy em seu próprio aplicativo. Nesta seção, você encontrará todas as informações necessárias para começar a usar esta API.

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

Criar uma tarefa de Multi-imagem para 3D

Este endpoint permite criar uma nova tarefa de Multi-imagem para 3D. Consulte O objeto de tarefa Multi-imagem para 3D para ver quais propriedades estão incluídas no objeto de tarefa Multi-imagem para 3D.

Parâmetros

Apenas um entre input_task_id ou image_urls é obrigató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 cuja saída (1 a 4 imagens) deve ser usada como entrada. Esta tarefa deve ser uma das seguintes: Texto para imagem, Imagem para imagem, Texto para imagem Multivista ou Imagem para imagem Multivista. Além disso, ela deve ter sido executada via API e ter status SUCCEEDED.

Name
image_urls
Type
array
Obrigatório
Description
Forneça de 1 a 4 imagens para o Meshy usar na criação do modelo. Atualmente oferecemos suporte aos formatos .jpg, .jpeg e .png. Todas as imagens devem retratar o mesmo objeto a partir de ângulos diferentes para obter melhores resultados.
Há duas formas de fornecer cada imagem:
- URL publicamente acessível: uma URL que é acessível pela internet pública.
- Data URI: um data URI da imagem codificado em base64. Exemplo de data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Para meshy-7 (ou latest), a primeira imagem é usada como a visão primária (frontal). A ordem das demais imagens não importa.

Name
ai_model
Type
string
padrão latest
Description
ID do modelo a ser usado. Valores disponíveis: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
ultra_mode
Type
boolean
padrão false
Description
Habilita a geração Ultra para geometria de maior fidelidade com detalhes de superfície mais refinados.
Suportado apenas quando ai_model é meshy-7 (ou latest).
Name
should_texture
Type
boolean
padrão true
Description
Determina se as texturas serão geradas. Definir como false pula a fase de texturização, fornecendo uma malha sem texturas.

Aplica-se somente quando should_texture = true

Name
enable_pbr
Type
boolean
padrão false
Description
Gera 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 mapa de emissão.
Name
texture_resolution
Type
string
padrão 2k
Description
Resolução da textura de cor base. Uma entre 2k (2048×2048), 4k (4096×4096) ou 8k (8192×8192). Resoluções mais altas capturam mais detalhes de superfície.
4k e 8k requerem ai_model meshy-6, meshy-7 ou latest. Em 8k, nenhum mapa de emissão é produzido.
Name
hd_texture
Type
boolean
⚠ obsoleto
padrão false
Description
Use texture_resolution em vez disso — equivalente a texture_resolution: "4k". Quando ambos são 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 800 caracteres.
Name
texture_image_url
Type
string
Description
Forneça uma imagem 2D para guiar o processo de texturização. Atualmente oferecemos suporte aos formatos .jpg, .jpeg e .png.
Há duas formas de fornecer a imagem:
- URL publicamente acessível: uma URL que é acessível pela internet pública
- Data URI: um data URI da imagem codificado em base64. Exemplo de data URI: data:image/jpeg;base64,<your base64-encoded image data>
A texturização por imagem pode não funcionar de forma otimizada se houver diferenças substanciais de geometria entre o asset original e a imagem enviada. Apenas um entre 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á usado para texturizar o modelo por padrão.
Name
texture_image_urls
Type
string[]
Description
Forneça de 1 a 4 imagens mostrando o mesmo objeto a partir de vistas diferentes para guiar a texturização. A primeira imagem é a visão primária (frontal); a ordem das demais vistas (esquerda, traseira, direita) não importa.
Cada elemento aceita os mesmos formatos que texture_image_url (uma URL publicamente acessível ou um data URI em base64, .jpg/.jpeg/.png).
Essas imagens guiam apenas a textura e são independentes de image_urls — as duas listas podem conter imagens diferentes e números diferentes de imagens.
Requer ai_model meshy-7 ou latest. Não pode ser combinado com texture_image_url ou texture_prompt.

Name
should_remesh
Type
boolean
padrão false (meshy-6), true (others)
Description
Controla se a fase de remesh deve ser habilitada. Para o modelo de mais alta qualidade, recomendamos definir should_remesh como false.

Aplica-se somente quando should_remesh = true

Name
topology
Type
string
padrão triangle
Description
Especifica a topology do modelo gerado.
Valores disponíveis:
- quad: gera uma malha predominantemente em quads.
- triangle: gera uma malha triangular decimada.
Name
target_polycount
Type
integer
padrão 30,000
Description
Especifica a quantidade alvo de polígonos no modelo gerado. O número real de polígonos pode variar em relação ao alvo, dependendo da complexidade da geometria.
O intervalo de valores válido varia de acordo com o nível do usuário:
- 100 a 300.000 (inclusive)
Name
decimation_mode
Type
integer
Description
Habilita a decimação adaptativa definindo um nível de contagem de polígonos. Quando definido, 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
padrão false
Description
Quando definido como true, o Meshy também armazena um arquivo GLB extra antes da conclusão da fase de remesh.

Name
symmetry_mode
Type
string
⚠ obsoleto
padrã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: desabilita a simetria.
- auto: determina e aplica automaticamente a simetria com base na geometria de entrada.
- on: força a simetria durante a geração.
Name
pose_mode
Type
string
padrão ""
Description
Especifica o mode 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
padrão false
Description
Use pose_mode em vez disso. Define se o modelo deve ser gerado em uma pose A/T.
Name
image_enhancement
Type
boolean
padrão true
Description
Otimiza as imagens de entrada para obter melhores resultados. Defina como false para preservar a aparência exata das imagens de entrada sem qualquer processamento de estilo.
Suportado apenas quando ai_model é meshy-6, meshy-7 ou latest.
Name
remove_lighting
Type
boolean
padrão true
Description
Remove realces e sombras da textura de cor base, produzindo um resultado mais limpo que funciona melhor com configurações de iluminação personalizadas.
Suportado apenas quando ai_model é meshy-6, meshy-7 ou latest.
Name
moderation
Type
boolean
padrão false
Description
Quando definido como true, o conteúdo de entrada será automaticamente verificado em busca de conteúdo potencialmente prejudicial. Se conteúdo prejudicial for detectado, a tarefa não avançará para a geração.
Cada imagem de image_urls e o texto de texture_prompt serão verificados.
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.
Valores disponíveis: glb, obj, fbx, stl, usdz, 3mf
Quando omitido, todos os formatos exceto 3mf são gerados. 3mf só é incluído quando especificado explicitamente.
Name
auto_size
Type
boolean
padrão false
Description
Quando definido como true, o serviço usa visão de IA para estimar automaticamente a altura real do objeto no mundo real e redimensionar o modelo de acordo. A origem será, por padrão, bottom, a menos que origin_at seja explicitamente definido.
Name
alpha_thumbnail
Type
boolean
padrão false
Description
Quando definido como true, a tarefa também renderiza uma versão com fundo transparente (RGBA) da pré-visualização e a retorna como alpha_thumbnail_url na resposta GET. O campo thumbnail_url existente permanece inalterado.
Name
multi_view_thumbnails
Type
boolean
padrão false
Description
Quando definido como true, a tarefa também renderiza quatro miniaturas de vistas cardinais (frontal, direita, traseira, esquerda) e as retorna em thumbnail_urls na resposta GET. O campo thumbnail_url existente permanece inalterado e continua apontando para a vista frontal, portanto os clientes existentes não são afetados.
Adiciona aproximadamente 3 segundos à latência da tarefa.

Aplica-se somente quando auto_size = true

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

Retornos

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

Modos de falha

Name
400 - Bad Request
Description
A solicitação foi inaceitável. Causas comuns:
- Parâmetro ausente: image_urls ou input_task_id deve ser fornecido.
- Tarefa de entrada inválida: input_task_id deve se referir a uma tarefa SUCCEEDED de Texto para imagem, Imagem para imagem, ou de uma variante multivista.
- Contagem de imagens inválida: image_urls deve conter entre 1 e 4 imagens, e texture_image_urls entre 1 e 4.
- Formato de imagem inválido: uma ou mais imagens em image_urls não estão em formatos suportados.
- Entradas de textura conflitantes: texture_image_urls não pode ser combinado com texture_image_url ou texture_prompt, e requer should_texture: true.
- Modelo não suportado para textura multivista: texture_image_urls requer ai_model meshy-7 ou latest.
- URL inacessível: um ou mais elementos de image_urls ou texture_image_urls não puderam ser baixados.
Name
401 - Unauthorized
Description
Falha na autenticação. Verifique sua chave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para executar esta tarefa.
Name
429 - Too Many Requests
Description
Você excedeu seu limite de taxa.

Request

POST

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

# Simple request
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>",
      "<your second publicly accessible image url or base64-encoded data URI>"
    ]
  }'

# With PBR texturing and GLB format
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>",
      "<your second publicly accessible image url or base64-encoded data URI>"
    ],
    "should_texture": true,
    "enable_pbr": true,
    "target_formats": ["glb"]
  }'

Response

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

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

Recuperar uma Tarefa de Multi-imagem para 3D

Este endpoint permite que você recupere uma tarefa de Multi-imagem para 3D dado um id de tarefa válido. Consulte O Objeto de Tarefa de Multi-imagem para 3D para ver quais propriedades estão incluídas no objeto de tarefa de Multi-imagem para 3D.

Parâmetros

Name
id
Type
path
Description
Identificador único para a tarefa de Multi-imagem para 3D a ser recuperada.

Retornos

A resposta contém o objeto de tarefa de Multi-imagem para 3D. Verifique a seção O Objeto de Tarefa de Multi-imagem para 3D para detalhes.

Request

GET

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

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-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/multi-image-to-3d/:id

Excluir uma Tarefa de Multi-imagem para 3D

Este endpoint exclui permanentemente uma tarefa de Multi-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 Multi-imagem para 3D a ser excluída.

Retornos

Retorna 200 OK em caso de sucesso.

Request

DELETE

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

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

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

Listar Tarefas de Multi-imagem para 3D

Este endpoint permite que você recupere uma lista de tarefas de Multi-imagem para 3D.

Parâmetros

Atributos opcionais

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

Retornos

Retorna uma lista paginada de Os Objetos de Tarefa de Multi-imagem para 3D.

Request

GET

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

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "multi-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/multi-image-to-3d/:id/stream

Transmitir uma Tarefa de Multi-imagem para 3D

Este endpoint transmite atualizações em tempo real para uma tarefa de Multi-imagem para 3D usando Server-Sent Events (SSE).

Parâmetros

Name
id
Type
path
Description
Identificador único para a tarefa de Multi-imagem para 3D a ser transmitida.

Retornos

Retorna um fluxo de Os Objetos de Tarefa de Multi-imagem para 3D como Server-Sent Events.

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

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/multi-image-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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-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 Multi-imagem para 3D

O objeto de tarefa Multi-imagem para 3D é uma unidade de trabalho que a Meshy monitora para gerar um modelo 3D a partir de várias imagens (entre 1 e 4, inclusive). As imagens devem ser do mesmo objeto, idealmente de diferentes vistas ou ângulos. O objeto possui as seguintes propriedades:

Propriedades

Name
id
Type
string
Description
Identificador único da tarefa. Embora usemos um UUID k-sortable para os ids de tarefa como detalhe de implementação, você não deve fazer suposições sobre o formato do id.
Name
type
Type
string
Description
Tipo da tarefa Multi-imagem para 3D. O valor é multi-image-to-3d.
Name
model_urls
Type
object
Description
URL para download do arquivo do modelo 3D com textura gerado pela Meshy. A propriedade de um formato será omitida caso o formato não tenha sido 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 as exportações OBJ quando há texturas presentes.
- Name
  stl
  Type
  string
  Description
  URL para download do arquivo STL.
- Name
  3mf
  Type
  string
  Description
  URL para download do arquivo 3MF. Presente apenas quando 3mf foi solicitado via target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  URL para download do arquivo GLB original de saída antes do remesh.
  Disponível apenas quando a tarefa foi criada com should_remesh: true e save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
URL para download da imagem de miniatura do arquivo do modelo. Equivalente a thumbnail_urls.front quando presente, mantido para compatibilidade com versões anteriores.
Name
alpha_thumbnail_url
Type
string
Description
URL para download de uma versão com fundo transparente (RGBA) de thumbnail_url. Presente apenas 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 de vistas cardinais do modelo 3D gerado. Cada valor é uma URL assinada para um PNG de 512×512 renderizado com os mesmos materiais e iluminação de thumbnail_url. Útil para pré-visualizar o modelo a partir de vários ângulos em pipelines em lote sem precisar baixar o GLB.
Presente apenas quando a tarefa foi criada com multi_view_thumbnails: true e atingiu o status SUCCEEDED. Tarefas mais antigas e tarefas criadas sem essa opção habilitada não incluirão este campo.
- Name
  front
  Type
  string
  Description
  Vista frontal, rotação de 0° em torno do eixo vertical (corresponde a thumbnail_url).
- Name
  right
  Type
  string
  Description
  Vista direita, rotação de 90°.
- Name
  back
  Type
  string
  Description
  Vista traseira, rotação de 180°.
- Name
  left
  Type
  string
  Description
  Vista esquerda, rotação de 270°.
Name
texture_prompt
Type
string
Description
O prompt de texto usado para guiar o processo de texturização.
Name
texture_image_urls
Type
string[]
Description
URLs para download das imagens de referência de textura que foram usadas para criar a tarefa, na ordem em que foram fornecidas. Presente apenas quando a tarefa foi criada com texture_image_urls.
Name
ultra_mode
Type
boolean
Description
Reflete o valor de ultra_mode com o qual a tarefa foi criada. Presente apenas em 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. Assim que a tarefa for concluída com sucesso, ela 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 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. Os 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 gerados pela tarefa. Normalmente, isso contém apenas um objeto de URL de textura. Cada URL de textura possui as seguintes propriedades:
- Name
  base_color
  Type
  string
  Description
  URL para download da imagem do mapa de cor base.
- Name
  metallic
  Type
  string
  Description
  URL para download da imagem 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 da imagem 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 da imagem 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 da imagem do mapa de emissão.
  Se a tarefa for criada com enable_pbr: false, ou se ai_model for meshy-5, esta propriedade será omitida.
Name
preceding_tasks
Type
integer
Description
A contagem de tarefas precedentes.
O valor deste campo só é significativo se o status da tarefa for PENDING.
Name
task_error
Type
object
Description
Detalhes do erro para tarefas com falha. Consulte 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 (os créditos são reembolsados em caso de falha).

Example Multi-Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-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,
}