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 Multi-imagem para 3D

Gere um modelo 3D a partir de uma a quatro imagens do mesmo objeto, capturadas de ângulos diferentes.


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

Create a Multi-Image to 3D task

Cria uma tarefa de Multi-imagem para 3D. A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa costuma levar, consulte Tempos de processamento. Para os campos que uma tarefa possui, consulte O objeto de tarefa Multi-imagem para 3D.

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 Ultra 2K geometry, 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>"
    ],
    "ai_model": "meshy-7.1",
    "geometry_resolution": "2k",
    "should_texture": true,
    "enable_pbr": true,
    "target_formats": ["glb"]
  }'

# Textured with Meshy N1 from the input images, the first as the front view
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 front view image url or base64-encoded data URI>",
      "<your back view image url or base64-encoded data URI>"
    ],
    "ai_model": "meshy-7.1",
    "texture_model": "meshy-n1"
  }'

Response

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

Parâmetros

  • Name
    input_task_id
    Type
    string
    Obrigatório
    Description

    Obrigatório, a menos que você envie image_urls. O ID de uma tarefa de Texto para imagem ou Imagem para imagem, incluindo uma de multivista. Meshy usa de uma a quatro imagens dessa tarefa como entrada. A tarefa deve ser uma que você criou com a API e que tenha o status SUCCEEDED.

  • Name
    image_urls
    Type
    array
    Obrigatório
    Description

    Obrigatório, a menos que você envie input_task_id. De uma a quatro imagens, cada uma como uma URL pública ou um Data URI, como data:image/jpeg;base64,<your base64-encoded image data>. Se você enviar ambos, Meshy usa input_task_id.

    Cada 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). Mais de quatro imagens retorna 400.

    Para obter os melhores resultados, as imagens devem mostrar o mesmo objeto sob ângulos diferentes. Com meshy-7.1 ou latest, Meshy usa a primeira imagem como a vista frontal, e a ordem das demais não importa.

  • Name
    ai_model
    Type
    string
    padrão latest
    Description

    O modelo de IA que gera o modelo 3D.

    Valores disponíveis:

    • latest: Meshy 7.1
    • meshy-7.1
    • meshy-6
    • meshy-6-lite
    • meshy-7: obsoleto, envie meshy-7.1 em vez disso. Será desativado em 31 de dezembro de 2026.

    Consulte Modelos para saber qual modelo se adequa ao seu projeto, como um objeto real ou uma impressão 3D.

  • Name
    geometry_resolution
    Type
    string
    padrão standard
    Description

    Quanto detalhe de geometria gerar.

    Valores disponíveis:

    • standard
    • 2k: executa a passagem Ultra em 2048³. Requer meshy-7.1, latest ou o meshy-7 obsoleto.
  • 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_texture
    Type
    boolean
    padrão true
    Description

    Se deve gerar texturas. true retorna um modelo texturizado, e false pula a etapa de textura e retorna uma malha sem texturas.

Aplica-se somente quando should_texture = true
  • Name
    texture_model
    Type
    string
    padrão depends on ai_model
    Description

    O modelo de IA que texturiza o modelo 3D a partir de várias vistas, na mesma tarefa. Deixe de fora para usar o modelo de textura padrão do seu ai_model. Isso não altera o custo em créditos.

    Valores disponíveis:

    • meshy-7: Meshy 7, com mapas PBR e texturas de até 8K
    • meshy-n1: Meshy N1, uma textura de cor base em 2K apenas a partir de imagens de referência

    Todo ai_model aceita ambos. Uma solicitação texturizada com meshy-6 ou meshy-6-lite retorna 400, assim como uma opção que o modelo de textura escolhido não suporta. Com should_texture: false, Meshy ignora texture_model, mas um valor desconhecido ainda retorna 400.

    Com meshy-n1, Meshy texturiza a partir de texture_image_urls ou texture_image_url, ou a partir das imagens de entrada quando você não envia nenhum dos dois. A primeira imagem é a vista frontal. Um modelo gerado com mais de 7.999.999 triângulos falha a tarefa, e Meshy reembolsa os créditos.

    Consulte Modelos para saber o que cada modelo de textura faz e qual escolher.

  • Name
    enable_pbr
    Type
    boolean
    padrão false
    Description

    Se também deve gerar mapas metálico, de rugosidade e normal, além da cor base. O modelo de textura Meshy 6 também gera um mapa de emissão, exceto em texture_resolution: 8k. Com texture_model: meshy-n1, true retorna 400.

  • Name
    texture_resolution
    Type
    string
    padrão 2k
    Description

    O tamanho da textura de cor base. Um tamanho maior captura mais detalhes de superfície.

    Valores disponíveis:

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

    4k e 8k requerem o modelo de textura Meshy 7 ou Meshy 6, e retornam 400 com os demais. Em 8k, 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, Meshy usa texture_resolution.

  • Name
    texture_prompt
    Type
    string
    Description

    Texto que guia a textura, com até 800 caracteres. Um texto mais longo retorna 400. Com texture_model: meshy-n1, enviá-lo retorna 400.

  • Name
    texture_image_url
    Type
    string
    Description

    Uma imagem 2D que guia a textura, como uma URL pública ou um Data URI, como data:image/jpeg;base64,<your base64-encoded image data>. 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).

    Se você enviar texture_image_url e texture_prompt juntos, Meshy usa texture_prompt. Com texture_model: meshy-n1, Meshy texturiza a partir dessa imagem como a vista frontal.

  • Name
    texture_image_urls
    Type
    string[]
    Description

    De uma a quatro imagens do objeto sob vistas diferentes que guiam a textura. Meshy usa a primeira imagem como a vista frontal. A ordem das demais vistas (esquerda, traseira, direita) não importa.

    Cada imagem segue as mesmas regras de texture_image_url. É uma URL pública ou um Data URI, em formato .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).

    Essas imagens guiam apenas a textura e não dependem de image_urls. As duas listas podem conter imagens diferentes e números diferentes de imagens.

    texture_image_urls requer o modelo de textura Meshy 7 ou Meshy N1. Envie-o com um destes:

    • ai_model igual a meshy-7.1, latest ou o meshy-7 obsoleto
    • texture_model igual a meshy-7 ou meshy-n1

    Você não pode enviá-lo com texture_image_url ou texture_prompt.

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

    Se deve refazer a malha (remesh) do modelo após a geração. Para o modelo 3D de maior qualidade, defina como false.

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

    O tipo de face do modelo com remesh.

    Valores disponíveis:

    • quad: uma malha predominantemente quad
    • triangle: uma malha triangular decimada

    Com texture_model: meshy-n1, quad retorna 400 quando o modelo passa por remesh, o que meshy-6-lite faz por padrão.

  • Name
    target_polycount
    Type
    integer
    padrão 30000
    Description

    O número de faces desejado, de 100 a 300000. O resultado pode diferir do alvo, dependendo da geometria do modelo. Um valor fora do intervalo retorna 400.

  • Name
    decimation_mode
    Type
    integer
    Description

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

    Valores disponíveis:

    • 1: ultra
    • 2: alta
    • 3: média
    • 4: baixa
  • Name
    save_pre_remeshed_model
    Type
    boolean
    padrão false
    Description

    Se também deve salvar o GLB de antes do remesh, retornado em model_urls.pre_remeshed_glb.

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

    Deixe de fora. Não afeta a saída.

    Valores disponíveis:

    • off: sem simetria
    • auto: simetria baseada na geometria de entrada
    • on: simetria forçada
  • Name
    pose_mode
    Type
    string
    Description

    A pose para um modelo de personagem, a-pose ou t-pose. Para não ter pose nenhuma, deixe de fora pose_mode e 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 uma pose A ou T.

  • Name
    image_enhancement
    Type
    boolean
    padrão true
    Description

    Se deve otimizar as imagens de entrada antes de gerar. false mantém o visual exato das imagens de entrada, sem processamento de estilo. Suportado apenas com meshy-6, meshy-7.1 ou latest. Enviá-lo com meshy-6-lite retorna 400.

  • 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 sua própria iluminação. Apenas o modelo de textura Meshy 6 o utiliza, e em texture_resolution: 8k ele sempre remove a iluminação. Com texture_model: meshy-n1, true retorna 400. Com ai_model: meshy-6-lite e seu modelo de textura padrão, enviá-lo retorna 400.

  • Name
    moderation
    Type
    boolean
    padrão false
    Description

    Se deve verificar as entradas em busca de conteúdo prejudicial. Meshy verifica cada imagem de entrada, texture_image_url ou cada imagem em texture_image_urls, e o texto em texture_prompt. Se Meshy encontrar conteúdo prejudicial, a solicitação retorna 400 e Meshy não cria uma tarefa.

  • Name
    target_formats
    Type
    string[]
    Description

    Os formatos de arquivo 3D a gerar. Meshy gera e retorna apenas os formatos que você listar, o que pode encurtar a tarefa.

    Valores disponíveis:

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

    Se você deixar de fora, Meshy gera todos os formatos, exceto 3mf. Meshy gera 3mf apenas quando você o lista.

  • Name
    auto_size
    Type
    boolean
    padrão false
    Description

    Se deve estimar a altura real do objeto no mundo real com visão de IA e redimensionar o modelo a essa altura. 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.

  • Name
    alpha_thumbnail
    Type
    boolean
    padrão false
    Description

    Se também deve renderizar uma prévia com fundo transparente (RGBA), retornada em alpha_thumbnail_url ao obter a tarefa. thumbnail_url não muda.

  • Name
    multi_view_thumbnails
    Type
    boolean
    padrão false
    Description

    Se também deve renderizar prévias frontal, direita, traseira e esquerda, retornadas em thumbnail_urls ao obter a tarefa. thumbnail_url não muda e continua mostrando a vista frontal. Isso adiciona cerca de 5 segundos à tarefa.

Retornos

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

    • Parâmetro ausente: Nem image_urls nem input_task_id foram enviados.
    • Tarefa de entrada inválida: input_task_id não é uma tarefa de Texto para imagem ou Imagem para imagem com status SUCCEEDED, nem uma de multivista.
    • Número de imagens inválido: image_urls ou texture_image_urls não contém de 1 a 4 imagens.
    • Formato de imagem inválido: Uma imagem em image_urls não está em um formato suportado.
    • Entradas de textura conflitantes: texture_image_urls foi enviado junto com texture_image_url, com texture_prompt, ou com should_texture: false.
    • Modelo não suportado para textura multivista: texture_image_urls foi enviado com ai_model igual a meshy-6 ou meshy-6-lite, a menos que texture_model seja meshy-7 ou meshy-n1.
    • URL inacessível: Meshy não consegue baixar uma imagem em image_urls ou texture_image_urls.
    • Imagem muito grande: Uma imagem em image_urls, texture_image_url ou texture_image_urls tem mais de 20 MB.
    • Tamanho de imagem inválido: Uma imagem em image_urls, texture_image_url ou texture_image_urls tem um lado menor que 32 pixels, ou mais de 178.956.970 pixels (largura × altura).
    • Resolução não suportada para entrada de múltiplas imagens: geometry_resolution é "4k", que este endpoint não suporta. Use 2k ou standard.
    • Modelo não suportado para opções de imagem: image_enhancement foi enviado com ai_model: "meshy-6-lite", ou remove_lighting foi enviado com ai_model: "meshy-6-lite" e seu modelo de textura padrão.
    • Modelo de textura inválido: texture_model não é um nome de modelo de textura válido.
    • Modelo de textura não disponível: Uma solicitação texturizada enviou texture_model igual a meshy-6 ou meshy-6-lite. Multi-imagem para 3D aceita apenas os modelos de textura que texturizam a partir de várias vistas. Envie meshy-7 ou meshy-n1, ou deixe texture_model de fora.
    • Opção não suportada para o modelo de textura: A solicitação pede ao modelo de textura uma opção que ele não suporta, como enable_pbr: true com meshy-n1 ou uma textura 4k com meshy-6-lite. Consulte Modelos.

    Corrija a solicitação e envie-a novamente. Consulte 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
    404 - Not Found
    Description

    input_task_id não corresponde a nenhuma das suas tarefas. Verifique o ID da tarefa e envie a solicitação novamente.

  • Name
    429 - Too Many Requests
    Description

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


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

Obter uma tarefa de Multi-imagem para 3D

Retorna uma tarefa de Multi-imagem para 3D pelo seu ID.

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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

Parâmetros

  • Name
    id
    Type
    path
    Description

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

Retornos

O objeto de tarefa de Multi-imagem para 3D.


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

Excluir uma tarefa de Multi-imagem para 3D

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

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

// 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 quando você a criou.

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 chegue a SUCCEEDED, FAILED ou CANCELED, e então a exclua.

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/v1/multi-image-to-3d

List Multi-Image to 3D tasks

Retorna uma lista das suas tarefas 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"
      }
    ],
    "preceding_tasks": 0,
    "task_error": null,

    "consumed_credits": 30
  }
]

Parâmetros

  • Name
    page_num
    Type
    integer
    padrão 1
    Description

    O número da página a retornar, 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

Retorno

Uma lista paginada de objetos de tarefa Multi-imagem para 3D.


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

Transmitir um stream de uma tarefa Multi-imagem para 3D

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

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.
// 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",
  "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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

Parâmetros

  • Name
    id
    Type
    path
    Description

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

Retorno

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

Um objeto de tarefa Multi-imagem para 3D descreve uma geração de um modelo 3D a partir de uma a quatro imagens de um objeto. Ele contém o status, o progresso e os arquivos do modelo quando a tarefa é bem-sucedida.

Propriedades

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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}
  • 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, sempre multi-image-to-3d.

  • Name
    model_urls
    Type
    object
    Description

    URLs de download para o modelo 3D gerado, uma para cada 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
      obj
      Type
      string
      Description

      O arquivo OBJ.

    • Name
      usdz
      Type
      string
      Description

      O arquivo USDZ.

    • Name
      mtl
      Type
      string
      Description

      O arquivo MTL, retornado junto com o arquivo OBJ quando o modelo tem texturas.

    • Name
      stl
      Type
      string
      Description

      O arquivo STL.

    • Name
      3mf
      Type
      string
      Description

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

    • Name
      pre_remeshed_glb
      Type
      string
      Description

      O arquivo GLB de antes do remesh. Presente apenas quando você criou a tarefa com should_remesh: true e save_pre_remeshed_model: true.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL de download para uma imagem de pré-visualização do modelo. É a mesma que thumbnail_urls.front quando esse campo está presente.

  • 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é-visualização transparente.

  • Name
    thumbnail_urls
    Type
    object
    Description

    URLs de download para pré-visualizações do modelo 3D vistas de quatro lados. Cada uma é uma URL assinada para um PNG de 512×512, renderizado com os mesmos materiais e iluminação de thumbnail_url. Você pode usá-las para visualizar o modelo de vários ângulos sem baixar o GLB.

    Presente apenas quando você criou a tarefa com multi_view_thumbnails: true e a tarefa atingiu o status SUCCEEDED. Uma tarefa criada sem multi_view_thumbnails: true não possui esse campo.

    • Name
      front
      Type
      string
      Description

      A vista frontal, a 0° em torno do eixo vertical. Corresponde a thumbnail_url.

    • Name
      right
      Type
      string
      Description

      A vista direita, a 90°.

    • Name
      back
      Type
      string
      Description

      A vista traseira, a 180°.

    • Name
      left
      Type
      string
      Description

      A vista esquerda, a 270°.

  • Name
    texture_prompt
    Type
    string
    Description

    O prompt de texto que guiou a textura.

  • Name
    texture_image_urls
    Type
    string[]
    Description

    URLs de download para as imagens de referência de textura com as quais você criou a tarefa, na ordem em que foram enviadas. Presente apenas quando você criou a tarefa com texture_image_urls.

  • Name
    ultra_mode
    Type
    boolean
    ⚠ obsoleto
    Description

    Consulte geometry_resolution em vez disso.

  • Name
    geometry_resolution
    Type
    string
    Description

    O nível Ultra em que a tarefa foi executada, que é 2k. Uma tarefa standard não tem esse campo.

  • Name
    progress
    Type
    integer
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

    Horário em que a tarefa começou, 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
    expires_at
    Type
    timestamp
    Description

    Horário em que os resultados da tarefa expiram, em milissegundos Unix.

  • Name
    finished_at
    Type
    timestamp
    Description

    Horário em que a tarefa terminou, em milissegundos Unix. É 0 até a tarefa terminar.

  • 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 que a tarefa gerou, 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. Não incluído quando você criou a tarefa com enable_pbr: false.

    • Name
      normal
      Type
      string
      Description

      O mapa de normais. Não incluído quando você criou a tarefa com enable_pbr: false.

    • Name
      roughness
      Type
      string
      Description

      O mapa de rugosidade. Não incluído quando você criou a tarefa com enable_pbr: false.

    • Name
      emission
      Type
      string
      Description

      O mapa de emissão. Incluído apenas quando você criou a tarefa com todos os itens a seguir:

      • ai_model: meshy-6, com seu modelo de textura padrão
      • enable_pbr: true
      • uma texture_resolution de 2k ou 4k
  • Name
    preceding_tasks
    Type
    integer
    Description

    O número de tarefas à frente desta na fila. O valor é significativo apenas 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. Consulte 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.