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

Imagem para 3D API

Transforme uma imagem em um modelo 3D, com ou sem texturas, nos formatos que você escolher. Envie a imagem, ou use o resultado de uma tarefa de Texto para imagem ou Imagem para imagem.


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

Criar uma tarefa de Imagem para 3D

Cria uma tarefa de Imagem para 3D. A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa costuma levar, consulte Tempos de processamento.

Request

POST
/openapi/v1/image-to-3d
# Simple request with required params
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": "<your publicly accessible image url or base64-encoded data URI>"
  }'

# With Ultra 4K geometry, remesh, PBR, and 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": "<your publicly accessible image url or base64-encoded data URI>",
    "ai_model": "meshy-7.1",
    "geometry_resolution": "4k",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

# Textured with Meshy N1 from the input image
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": "<your publicly accessible 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_url. O ID de uma tarefa de Texto para imagem ou Imagem para imagem cuja imagem você deseja usar como entrada. A tarefa deve ser uma que você criou com a API, deve ter o status SUCCEEDED e deve ter produzido exatamente uma imagem.

  • Name
    image_url
    Type
    string
    Obrigatório
    Description

    Obrigatório, a menos que você envie input_task_id. A imagem a ser transformada em um modelo 3D, como uma URL pública ou um Data URI codificado em base64, como data:image/jpeg;base64,<seus dados de imagem codificados em base64>. Se você enviar ambos, o Meshy usa input_task_id.

    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).

  • Name
    model_type
    Type
    string
    padrão standard
    Description

    O tipo de malha 3D a ser gerada.

    Valores disponíveis:

    • standard: uma malha de alto detalhe
    • smart-topology: uma malha de um modelo Smart Topology, que você escolhe com ai_model (meshy-t2 ou meshy-t2.5)

    Com smart-topology, o Meshy ignora should_remesh, save_pre_remeshed_model e decimation_mode, e aceita apenas topology: triangle.

  • Name
    ai_model
    Type
    string
    padrão latest
    Description

    O modelo de IA que gera o modelo 3D. Os valores disponíveis dependem de model_type.

    Modelos padrão (model_type: standard):

    • latest: Meshy 7.1
    • meshy-7.1
    • meshy-6
    • meshy-6-lite
    • meshy-7 (obsoleto): use meshy-7.1 em vez disso. Ele se aposenta em 31 de dezembro de 2026.

    Modelos Smart Topology (model_type: smart-topology) produzem triângulos, em uma contagem de faces que você pode definir com target_polycount:

    • meshy-t2: topologia mais limpa e partes nativamente separadas
    • meshy-t2.5 (padrão): detalhe mais nítido para assets de jogos

    Consulte Modelos para saber qual modelo se adapta ao seu projeto, como um personagem de jogo ou uma impressão 3D.

  • Name
    geometry_resolution
    Type
    string
    padrão standard
    Description

    A etapa de geração de geometria.

    Valores disponíveis:

    • standard
    • 2k: executa a etapa Ultra em 2048³
    • 4k: executa a etapa Ultra em 4096³, para o máximo de detalhe de superfície

    2k precisa de meshy-7.1, latest, ou do meshy-7 obsoleto. 4k precisa de meshy-7.1 ou latest.

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

    Use 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 ignora a texturização e retorna uma malha sem textura.

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, na mesma tarefa. Omita 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
    • meshy-6-lite: Meshy 6 Lite, uma textura em 2K com o menor custo
    • meshy-6: Meshy 6, apenas como padrão para ai_model: meshy-6

    Todo ai_model aceita meshy-7, meshy-n1 e meshy-6-lite. Uma opção que o modelo de textura escolhido não suporta retorna 400. Com meshy-n1, um modelo gerado com mais de 7.999.999 triângulos falha a tarefa, e o Meshy reembolsa os créditos. Com should_texture: false, o Meshy ignora texture_model, mas um valor desconhecido ainda retorna 400.

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

  • Name
    enable_pbr
    Type
    boolean
    padrão false
    Description

    Se deve também gerar mapas PBR (metálico, rugosidade e normal) além da cor base. true requer should_texture: true, e retorna 400 com should_texture: false. Com texture_model: meshy-n1, true retorna 400.

    O modelo de textura Meshy 6 também gera um mapa de emissão, exceto em texture_resolution: 8k.

  • Name
    texture_resolution
    Type
    string
    padrão 2k
    Description

    O tamanho da textura de cor base. Uma textura maior captura mais detalhe de superfície.

    Valores disponíveis:

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

    4k e 8k precisam do modelo de textura Meshy 7 ou Meshy 6, e retornam 400 com os outros. Em 8k, o Meshy não produz um mapa de emissão.

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

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

  • Name
    texture_prompt
    Type
    string
    Description

    Texto que 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 que guia a textura, como uma URL pública ou um Data URI codificado em base64, como data:image/jpeg;base64,<seus dados de imagem codificados em base64>. A imagem deve ser um arquivo JPG, JPEG, PNG ou WebP de no máximo 20 MB, com pelo menos 32 pixels em cada lado, e no máximo 178.956.970 pixels (largura × altura).

    O Meshy guia a textura usando apenas um entre texture_prompt e texture_image_url. Se você enviar ambos, o Meshy usa texture_prompt. Para o custo em créditos da texturização, consulte Preços.

    Com texture_model: meshy-n1, o Meshy texturiza a partir dessa imagem como a vista frontal, ou a partir da imagem de entrada quando você a omite.

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

    Se deve executar a fase de remesh. Para o modelo 3D de mais alta 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 remeshado.

    Valores disponíveis:

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

    A saída do Smart Topology é apenas triangular, então quad com meshy-t2 ou meshy-t2.5 retorna 400. Com texture_model: meshy-n1, quad retorna 400 quando o modelo é remeshado, o que meshy-6-lite faz por padrão.

  • Name
    decimation_mode
    Type
    integer
    Description

    Contagem de faces adaptativa, por nível. Quando você a define, o 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 deve também armazenar um GLB do modelo antes da fase de remesh. O Meshy o retorna em model_urls.pre_remeshed_glb.

  • Name
    target_polycount
    Type
    integer
    Description

    O número de faces a atingir. O resultado pode diferir da meta, dependendo da geometria do modelo.

    Aplica-se em dois casos separados:

    • Remesh: Quando should_remesh é true em um modelo standard, o Meshy decima a malha para cerca dessa contagem. Se você definir decimation_mode, o Meshy o usa e ignora target_polycount.
    • Smart Topology: Quando model_type é smart-topology e ai_model é meshy-t2 ou meshy-t2.5, o Meshy gera o modelo com essa contagem de faces. Nenhum remesh é executado, e você não precisa de should_remesh.

    O intervalo e o padrão dependem do caso:

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

    Um valor fora do intervalo retorna 400.

    Para um asset de jogo low-poly, use um modelo Smart Topology em vez de remeshar um modelo padrão. Consulte Modelos.

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

    Omita, pois não afeta a saída. Seus valores controlavam a simetria durante a geração:

    • off: sem simetria
    • auto: simetria escolhida a partir da 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, omita pose_mode e is_a_t_pose.

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

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

  • Name
    surface_mode
    Type
    string
    ⚠ obsoleto
    Description

    Use ai_model em vez disso. Não afeta a saída, porque a geração de modelo que ele selecionava está aposentada.

    Os valores aceitos são organic e hard. Qualquer outro valor retorna 400.

  • Name
    image_enhancement
    Type
    boolean
    padrão true
    Description

    Se deve otimizar a imagem de entrada antes de gerar. false mantém o visual exato da imagem de entrada, sem processamento de estilo.

    Funciona apenas com meshy-6, meshy-7.1 ou latest. Com meshy-6-lite ou model_type: smart-topology, 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 e funciona melhor sob sua própria iluminação.

    Só tem efeito com o modelo de textura Meshy 6, e um modelo de textura que não o suporta retorna 400 para true. Com model_type: smart-topology, ou 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 examinar essas entradas em busca de conteúdo nocivo antes de gerar:

    • image_url
    • texture_image_url
    • texture_prompt

    Se o Meshy detectar conteúdo nocivo, a requisição retorna 400 e o Meshy não cria a tarefa.

  • Name
    target_formats
    Type
    string[]
    Description

    Os formatos de arquivo a gerar. O Meshy gera e retorna apenas os formatos que você listar, o que pode encurtar a tarefa. Se você omitir, o Meshy gera todos os formatos, exceto 3mf, que você só obtém se o listar.

    Valores disponíveis:

    • glb
    • obj
    • fbx
    • stl
    • usdz
    • 3mf
  • 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 para essa altura. O Meshy coloca a origem na parte inferior, a menos que você defina origin_at.

  • Name
    alpha_thumbnail
    Type
    boolean
    padrão false
    Description

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

  • Name
    multi_view_thumbnails
    Type
    boolean
    padrão false
    Description

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

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

    Onde colocar a origem do modelo, bottom ou center.

Retornos

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

Modos de falha

  • Name
    400 - Bad Request
    Description

    A requisição não pode ser executada. A mensagem de erro informa qual problema foi encontrado. Por exemplo:

    • Parâmetro ausente: Nem image_url 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 que produziu exatamente uma imagem.
    • Formato de imagem inválido: A imagem de image_url não é um arquivo JPG, JPEG, PNG ou WebP.
    • URL inacessível: O Meshy não consegue baixar a imagem de image_url, porque a URL retorna 404 ou expira o tempo de espera.
    • Imagem muito grande: A imagem de image_url ou texture_image_url tem mais de 20 MB.
    • Tamanho de imagem inválido: A imagem de image_url ou texture_image_url tem um lado menor que 32 pixels, ou mais de 178.956.970 pixels (largura × altura).
    • Data URI inválido: A string base64 está malformada.
    • Combinação de parâmetros inválida: enable_pbr é true, e should_texture é false.
    • Modelo não suportado para Ultra: geometry_resolution é 2k ou 4k, com um ai_model que não consegue executá-lo.
    • Modelo não suportado para opções de imagem: um destes:
      • image_enhancement foi enviado com ai_model: "meshy-6-lite" ou model_type: "smart-topology".
      • remove_lighting foi enviado com model_type: "smart-topology", ou com ai_model: "meshy-6-lite" e seu modelo de textura padrão.
    • Modelo de textura inválido: texture_model não é um dos valores disponíveis.
    • Modelo de textura não disponível: texture_model é meshy-6 com um ai_model diferente de meshy-6. Envie meshy-7, meshy-n1 ou meshy-6-lite, ou omita.
    • Opção não suportada para o modelo de textura: A requisição solicita 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 requisiçã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 requisiçã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/image-to-3d/:id

Obter uma tarefa Imagem para 3D

Retorna uma tarefa Imagem para 3D pelo seu ID.

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

Parâmetros

  • Name
    id
    Type
    path
    Description

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

Retorna

O objeto de tarefa Imagem para 3D.


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

Excluir uma tarefa de Imagem para 3D

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

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

// 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 rota

  • Name
    id
    Type
    path
    Description

    O ID da tarefa a ser excluída.

Status da tarefa

Excluir uma tarefa PENDING reembolsa os créditos usados na sua criação.

Uma tarefa IN_PROGRESS não pode ser excluída. A requisiçã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/image-to-3d

Listar tarefas de Imagem para 3D

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

Parâmetros

  • Name
    page_num
    Type
    integer
    padrão 1
    Description

    O número da página a ser retornada, até 255. Um valor maior retorna 400.

  • Name
    page_size
    Type
    integer
    padrão 10
    Description

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

  • Name
    sort_by
    Type
    string
    Description

    A ordem de classificação.

    Valores disponíveis:

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

Retornos

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


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

Transmitir uma tarefa de Imagem para 3D em stream

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

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

// 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": "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": null,
  "consumed_credits": 30
}

Parâmetros

  • Name
    id
    Type
    path
    Description

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

Retornos

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

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

Propriedades

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": 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 image-to-3d.

  • Name
    model_urls
    Type
    object
    Description

    URLs de download para o modelo 3D gerado, uma por formato de arquivo. Um formato que a tarefa não gerou não tem chave, em vez de uma string vazia.

    • Name
      glb
      Type
      string
      Description

      O arquivo GLB.

    • Name
      fbx
      Type
      string
      Description

      O arquivo FBX.

    • Name
      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 um 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 3D. Quando thumbnail_urls está presente, é a mesma imagem que thumbnail_urls.front. A Meshy a mantém para compatibilidade retroativa.

  • 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 a partir de quatro lados. Cada valor é uma URL assinada para um PNG de 512×512, renderizado com os mesmos materiais e iluminação que thumbnail_url. Use-as para pré-visualizar o modelo a partir de vários ângulos, por exemplo em um pipeline em lote, sem baixar o GLB.

    Presente apenas quando você criou a tarefa com multi_view_thumbnails: true e a tarefa atingiu SUCCEEDED. Tarefas criadas sem multi_view_thumbnails: true não incluem este campo.

    • Name
      front
      Type
      string
      Description

      A visão frontal, a 0° em torno do eixo vertical. Corresponde a thumbnail_url.

    • Name
      right
      Type
      string
      Description

      A visão à direita, a 90°.

    • Name
      back
      Type
      string
      Description

      A visão traseira, a 180°.

    • Name
      left
      Type
      string
      Description

      A visão à esquerda, a 270°.

  • Name
    texture_prompt
    Type
    string
    Description

    O prompt de texto que guiou a textura.

  • Name
    texture_image_url
    Type
    string
    Description

    URL de download para a imagem que guiou a textura.

  • Name
    ultra_mode
    Type
    boolean
    ⚠ obsoleto
    Description

    Leia geometry_resolution em vez disso.

  • Name
    geometry_resolution
    Type
    string
    Description

    O nível Ultra em que a tarefa foi executada, 2k ou 4k. Uma tarefa standard não inclui este campo.

  • Name
    progress
    Type
    integer
    Description

    Quanto da tarefa está concluído, em porcentagem. É 0 até a tarefa começar e 100 quando é 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 o resultado da tarefa expira, 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

    Os mapas de textura que a tarefa gerou, como um array de objetos. Geralmente contém um objeto, com estes campos:

    • Name
      base_color
      Type
      string
      Description

      URL de download para o mapa de cor base.

    • Name
      metallic
      Type
      string
      Description

      URL de download para o mapa metálico. O campo está ausente quando você criou a tarefa com enable_pbr: false.

    • Name
      normal
      Type
      string
      Description

      URL de download para o mapa de normais. O campo está ausente quando você criou a tarefa com enable_pbr: false.

    • Name
      roughness
      Type
      string
      Description

      URL de download para o mapa de rugosidade. O campo está ausente quando você criou a tarefa com enable_pbr: false.

    • Name
      emission
      Type
      string
      Description

      URL de download para o mapa de emissão. A Meshy o inclui apenas quando você criou a tarefa com todos estes:

      • 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. Veja Erros.

  • Name
    consumed_credits
    Type
    integer
    Description

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