API de Imagem para 3D

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

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

Create an Image to 3D Task

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

A tarefa é executada em segundo plano. Para saber quanto tempo normalmente demora, consulte Tempos de processamento.

Parâmetros

Apenas um dos input_task_id ou image_url é 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 cujo resultado deve ser usado como imagem de entrada. Esta tarefa deve ser uma das seguintes: Texto para imagem ou Imagem para imagem. Além disso, deve ter sido executada através da API, ter um estado SUCCEEDED e produzir exatamente uma imagem.

Name
image_url
Type
string
Obrigatório
Description
Forneça uma imagem para a Meshy utilizar na criação do modelo. Atualmente, suportamos os formatos .jpg, .jpeg, .png e .webp.
Tamanho máximo do ficheiro: 20 MB.
Existem duas formas de fornecer a imagem:
- URL publicamente acessível: Um URL acessível a partir da internet pública.
- Data URI: Um data URI da imagem codificado em base64. Exemplo de um data URI: data:image/jpeg;base64,<your base64-encoded image data>.

Name
model_type
Type
string
predefinição standard
Description
Especifique o tipo de geração de malha 3D.
Valores disponíveis:
- standard: Geração de malha 3D regular de alto detalhe.
- smart-topology: Escolha um modelo Smart Topology com ai_model (meshy-t2 ou meshy-t2.5).
- lowpoly (obsoleto, a ser descontinuado a 30 de outubro de 2026): Gera malha low-poly otimizada para polígonos mais limpos. Recomendamos antes o Meshy T2.5: smart-topology com meshy-t2.5.
Quando smart-topology é selecionado, should_remesh, save_pre_remeshed_model e decimation_mode são ignorados, e apenas topology: triangle é aceite.
lowpoly será descontinuado a 30 de outubro de 2026. Após essa data, os pedidos com model_type: "lowpoly" devolverão um erro. Recomendamos mudar para o Meshy T2.5 (model_type: "smart-topology" com ai_model: "meshy-t2.5"). Quando lowpoly é selecionado, ai_model, topology, target_polycount, should_remesh e save_pre_remeshed_model são ignorados.
Name
ai_model
Type
string
predefinição latest
Description
ID do modelo a utilizar. Os valores disponíveis dependem de model_type.
Geração standard (model_type: standard):
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (obsoleto): utilize meshy-7.1 em vez disso.
Geração Smart Topology (model_type: smart-topology):
- meshy-t2: o modelo Smart Topology — topology mais limpa, partes naturalmente separadas, resultado em triângulos e uma contagem de faces que pode definir com target_polycount.
- meshy-t2.5 (predefinição): Detalhe mais nítido para assets de jogos. Resultado em triângulos e uma contagem de faces que pode definir com target_polycount.
Name
geometry_resolution
Type
string
predefinição standard
Description
Passagem de geração de geometria. 2k executa a passagem Ultra a 2048³; 4k executa-a a 4096³ para o detalhe de superfície mais fino.
Valores disponíveis: standard, 2k, 4k
Requer meshy-7.1 ou latest.
Name
ultra_mode
Type
boolean
⚠ obsoleto
predefinição false
Description
Utilize geometry_resolution em vez disso. ultra_mode: true equivale a geometry_resolution: "2k".
Name
should_texture
Type
boolean
predefinição true
Description
Determina se as texturas são geradas. Definir como false ignora a fase de textura, fornecendo uma malha sem texturas.

Aplica-se apenas quando should_texture = true

Name
enable_pbr
Type
boolean
predefinição false
Description
Gera mapas PBR (metálico, rugosidade, normal) para além da cor base. Um mapa de emissão também é incluído quando ai_model é meshy-6, exceto a texture_resolution: 8k. meshy-6-lite, meshy-7.1, meshy-t2 e latest não produzem um mapa de emissão.
Name
texture_resolution
Type
string
predefinição 2k
Description
Resolução da textura de cor base. Uma de 2k (2048×2048), 4k (4096×4096) ou 8k (8192×8192). Resoluções mais elevadas captam mais detalhe de superfície.
4k e 8k não estão disponíveis com ai_model meshy-6-lite. A 8k, não é produzido nenhum mapa de emissão.
Name
hd_texture
Type
boolean
⚠ obsoleto
predefinição false
Description
Utilize texture_resolution em vez disso — equivale a texture_resolution: "4k". Quando ambos são definidos, texture_resolution tem prioridade.
Name
texture_prompt
Type
string
Description
Forneça um prompt de texto para orientar o processo de texturização. Máximo de 800 caracteres.
Name
texture_image_url
Type
string
Description
Forneça uma imagem 2D para orientar o processo de texturização. Atualmente, suportamos os formatos .jpg, .jpeg, .png e .webp.
Tamanho máximo do ficheiro: 20 MB.
Existem duas formas de fornecer a imagem:
- URL publicamente acessível: Um URL acessível a partir da internet pública
- Data URI: Um data URI da imagem codificado em base64. Exemplo de um data URI: data:image/jpeg;base64,<your base64-encoded image data>
A texturização de imagem pode não funcionar de forma ideal se existirem diferenças geométricas substanciais entre o asset original e a imagem carregada. Apenas um dos parâmetros texture_image_url ou texture_prompt pode ser utilizado para orientar o processo de texturização. Se ambos os parâmetros forem fornecidos, texture_prompt será utilizado por predefinição para texturizar o modelo. A texturização, quer por texto quer por imagem, custa 10 créditos por tarefa.

Name
should_remesh
Type
boolean
predefinição false (Meshy 6 and Meshy 7 models), true (others)
Description
Controla se a fase de remesh é ativada. Para obter o modelo da mais alta qualidade, recomendamos definir should_remesh como false.

Aplica-se apenas quando should_remesh = true

Name
topology
Type
string
predefinição triangle
Description
Especifique a topology do modelo gerado.
Valores disponíveis:
- quad: Gera uma malha predominantemente de quadriláteros.
- triangle: Gera uma malha de triângulos decimada.
O resultado do Smart Topology é apenas em triângulos. Solicitar quad em conjunto com ai_model meshy-t2 ou meshy-t2.5 devolve um erro.
Name
decimation_mode
Type
integer
Description
Ative 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
predefinição false
Description
Quando definido como true, a Meshy também guarda um ficheiro GLB adicional antes de a fase de remesh ser concluída.

Name
target_polycount
Type
integer
Description
Número alvo de polígonos (faces) no resultado. A contagem real pode diferir do alvo consoante a geometria.
target_polycount tem efeito em dois casos independentes:
- Remesh — com should_remesh: true num modelo standard. A malha sofre remesh (é decimada) para aproximadamente esta contagem. Intervalo de 100 a 300 000, predefinição 30 000. Se decimation_mode estiver definido, tem prioridade e target_polycount é ignorado.
- Smart Topology — com model_type: smart-topology e ai_model meshy-t2 ou meshy-t2.5. O modelo é gerado diretamente com esta contagem de faces; não é executado nenhum remesh e should_remesh não é necessário. Para meshy-t2: intervalo de 100 a 15 000, predefinição 4 000. Para meshy-t2.5: intervalo de 100 a 30 000, predefinição 15 000.

Name
symmetry_mode
Type
string
⚠ obsoleto
predefinição auto
Description
Obsoleto. Este parâmetro já não afeta o resultado.
O campo symmetry_mode controla o comportamento de simetria durante o processo de geração do modelo.
Os valores válidos são:
- off: Desativa a simetria.
- auto: Determina e aplica automaticamente a simetria com base na geometria de entrada.
- on: Impõe simetria durante a geração.
Name
pose_mode
Type
string
predefinição ""
Description
Especifique o modo de pose para o modelo gerado.
Valores disponíveis:
- a-pose: Gera o modelo numa pose A.
- t-pose: Gera o modelo numa pose T.
- "" (cadeia vazia): Nenhuma pose específica aplicada.
Name
is_a_t_pose
Type
boolean
⚠ obsoleto
predefinição false
Description
Utilize pose_mode em vez disso. Indica se deve gerar o modelo numa pose A/T.
Name
surface_mode
Type
string
⚠ obsoleto
Description
Já não afeta o resultado. Selecionava uma geração de modelo que entretanto foi descontinuada; utilize ai_model em vez disso.
Os valores aceites são organic e hard; qualquer outro valor devolve 400.
Name
image_enhancement
Type
boolean
predefinição true
Description
Otimiza a imagem de entrada para obter melhores resultados. Defina como false para preservar o aspeto exato da imagem de entrada sem qualquer processamento de estilo.
Apenas suportado quando ai_model é meshy-6, meshy-7.1 ou latest. Defini-lo com meshy-6-lite ou com model_type: smart-topology devolve um erro.
Name
remove_lighting
Type
boolean
predefinição true
Description
Remove reflexos e sombras da textura de cor base, produzindo um resultado mais limpo que funciona melhor sob configurações de iluminação personalizadas.
Só tem efeito quando ai_model é meshy-6. meshy-7.1 e latest aceitam-no e ignoram-no. Defini-lo com meshy-6-lite ou com model_type: smart-topology devolve um erro.
Name
moderation
Type
boolean
predefinição false
Description
Quando definido como true, o conteúdo de entrada será automaticamente analisado para deteção de conteúdo potencialmente prejudicial. Se for detetado conteúdo prejudicial, a tarefa não avançará para a geração.
O conteúdo das entradas image_url, texture_image_url e texture_prompt será analisado.
Name
target_formats
Type
string[]
Description
Especifica quais os formatos de ficheiro 3D a incluir no resultado. Apenas os formatos solicitados serão gerados e devolvidos, o que pode reduzir o tempo de conclusão da tarefa. Quando omitido, todos os formatos suportados são incluídos.
Valores disponíveis: glb, obj, fbx, stl, usdz, 3mf
Quando omitido, são gerados todos os formatos exceto 3mf. 3mf só é incluído quando especificado explicitamente.
Name
auto_size
Type
boolean
predefinição false
Description
Quando definido como true, o serviço utiliza visão por IA para estimar automaticamente a altura real do objeto e redimensionar o modelo em conformidade. A origem será bottom por predefinição, a menos que origin_at seja explicitamente definido.
Name
alpha_thumbnail
Type
boolean
predefinição false
Description
Quando definido como true, a tarefa gera adicionalmente uma versão com fundo transparente (RGBA) da pré-visualização e devolve-a como alpha_thumbnail_url na resposta GET. O campo thumbnail_url existente permanece inalterado.
Name
multi_view_thumbnails
Type
boolean
predefinição false
Description
Quando definido como true, a tarefa gera adicionalmente quatro miniaturas de vistas cardeais (frente, direita, trás, esquerda) e devolve-as em thumbnail_urls na resposta GET. O campo thumbnail_url existente permanece inalterado e continua a apontar para a vista frontal, pelo que os clientes existentes não são afetados.
Acrescenta aproximadamente 3 segundos à latência da tarefa.

Aplica-se apenas quando auto_size = true

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

Retorna

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

Modos de falha

Name
400 - Bad Request
Description
O pedido não foi aceite. Causas comuns:
- Parâmetro em falta: É necessário fornecer image_url ou input_task_id.
- Tarefa de entrada inválida: O input_task_id deve referir-se a uma tarefa de Texto para imagem ou Imagem para imagem com estado SUCCEEDED que produza exatamente uma imagem.
- Formato de imagem inválido: O image_url fornecido não está num formato suportado (.jpg, .jpeg, .png, .webp).
- URL inacessível: Não foi possível transferir o image_url (404 ou timeout).
- Imagem demasiado grande: A imagem image_url ou texture_image_url excede 20 MB.
- Data URI inválido: A cadeia base64 está mal formada.
- Combinação de parâmetros inválida: enable_pbr só é suportado quando should_texture é verdadeiro.
- Modelo não suportado para low poly: ai_model: "meshy-6-lite" não suporta model_type: "lowpoly".
- Modelo não suportado para Ultra: geometry_resolution requer meshy-7.1 ou latest.
- Modelo não suportado para opções de imagem: image_enhancement ou remove_lighting está definido com ai_model: "meshy-6-lite" ou model_type: "smart-topology".
Name
401 - Unauthorized
Description
A autenticação falhou. Verifique a sua chave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarefa.
Name
429 - Too Many Requests
Description
Excedeu o seu limite de taxa.

Request

POST

/openapi/v1/image-to-3d

# 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"]
  }'

Response

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

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

Obter uma tarefa de Imagem para 3D

Este endpoint permite obter uma tarefa de Imagem para 3D através de um id de tarefa válido. Consulte O objeto de tarefa de Imagem para 3D para ver quais propriedades estão incluídas no objeto de tarefa de Imagem para 3D.

Parâmetros

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

Retorno

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

Request

GET

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

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}

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

Eliminar uma Tarefa de Imagem para 3D

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

Parâmetros de Path

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

Estado da Tarefa

Uma tarefa que ainda esteja PENDING é eliminada e os créditos consumidos no momento da criação são reembolsados.

Uma tarefa que já esteja IN_PROGRESS não pode ser eliminada: o pedido é rejeitado com 409 Conflict e a tarefa continua a ser executada. Os créditos de uma tarefa que o worker já começou a processar não são reembolsáveis, pelo que eliminá-la a meio da execução custar-lhe-ia tanto os créditos como o resultado. Aguarde até que atinja o estado SUCCEEDED, FAILED ou CANCELED e, só então, elimine-a.

Uma tarefa num estado terminal (SUCCEEDED, FAILED ou CANCELED) é eliminada sem reembolso.

Retorna

Retorna 200 OK em caso de sucesso, ou 409 Conflict quando a tarefa está IN_PROGRESS.

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 is left 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."
}

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

Listar Tarefas de Imagem para 3D

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

Parâmetros

Atributos opcionais

Name
page_num
Type
integer
Description
Número da página para paginação. Começa e tem como valor predefinido 1.
Name
page_size
Type
integer
Description
Limite do tamanho da página. O valor predefinido é 10 itens. O máximo permitido é 100 itens.
Name
sort_by
Type
string
Description
Campo pelo qual ordenar. Valores disponíveis:
- +created_at: Ordena por hora de criação em ordem ascendente.
- -created_at: Ordena por hora de criação em ordem descendente.

Devolve

Devolve uma lista paginada de Objetos de Tarefa de Imagem para 3D.

Request

GET

/openapi/v1/image-to-3d

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-3d",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
      "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "thumbnail_urls": {
      "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
      "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
      "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
      "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
    },
    "texture_prompt": "",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "expires_at": 1692771679037,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
        "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
        "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
        "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
        "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {
      "message": ""
    },
    "consumed_credits": 30
  }
]

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

Transmitir em Stream uma Tarefa de Imagem para 3D

Este endpoint transmite atualizações em tempo real para uma tarefa de Imagem para 3D através de Server-Sent Events (SSE).

Parâmetros

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

Devolve

Devolve um stream de The Image to 3D Task Objects como Server-Sent Events.

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

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.
// 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": "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 Imagem para 3D

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

Propriedades

Name
id
Type
string
Description
Identificador único da tarefa. Embora utilizemos um UUID k-sortable para os ids de tarefa como detalhe de implementação, não deve fazer nenhuma suposição sobre o formato do id.
Name
type
Type
string
Description
Tipo da tarefa Imagem para 3D. O valor é image-to-3d.
Name
model_urls
Type
object
Description
URL para download do ficheiro de modelo 3D texturizado gerado pela Meshy. A propriedade de um formato será omitida se o formato não for gerado, em vez de devolver uma string vazia.
- Name
  glb
  Type
  string
  Description
  URL para download do ficheiro GLB.
- Name
  fbx
  Type
  string
  Description
  URL para download do ficheiro FBX.
- Name
  obj
  Type
  string
  Description
  URL para download do ficheiro OBJ.
- Name
  usdz
  Type
  string
  Description
  URL para download do ficheiro USDZ.
- Name
  mtl
  Type
  string
  Description
  URL para download do ficheiro MTL, devolvido juntamente com as exportações OBJ quando existem texturas.
- Name
  stl
  Type
  string
  Description
  URL para download do ficheiro STL.
- Name
  3mf
  Type
  string
  Description
  URL para download do ficheiro 3MF. Apenas presente quando 3mf foi pedido através de target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  URL para download do resultado GLB original antes do remesh.
  Disponível apenas quando a tarefa foi criada com should_remesh: true e save_pre_remeshed_model: true em simultâneo.
Name
thumbnail_url
Type
string
Description
URL para download da imagem de miniatura do ficheiro de 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. Apenas presente quando a tarefa foi criada com alpha_thumbnail: true e a pré-visualização transparente foi renderizada com sucesso; caso contrário, este campo é omitido.
Name
thumbnail_urls
Type
object
Description
URLs para download de quatro miniaturas de vistas cardeais do modelo 3D gerado. Cada valor é um URL assinado para um PNG de 512×512 renderizado com os mesmos materiais e iluminação que thumbnail_url. Útil para pré-visualizar o modelo a partir de vários ângulos em pipelines em lote sem transferir o GLB.
Apenas presente quando a tarefa foi criada com multi_view_thumbnails: true e atingiu o estado SUCCEEDED. Tarefas mais antigas e tarefas criadas sem esta opção 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 que foi utilizado para orientar o processo de texturização.
Name
texture_image_url
Type
string
Description
URL para download da imagem de textura que foi utilizada para orientar o processo de texturização.
Name
ultra_mode
Type
boolean
⚠ obsoleto
Description
Obsoleto; consulte geometry_resolution em vez disso.
Name
geometry_resolution
Type
string
Description
O nível Ultra em que a tarefa foi executada (2k ou 4k); omitido para standard.
Name
progress
Type
integer
Description
Progresso da tarefa. Se a tarefa ainda não tiver começado, esta propriedade será 0. Assim que a tarefa for bem-sucedida, esta passará a ser 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 tiver começado, esta propriedade será 0.
Um carimbo de data/hora representa o número de milissegundos decorridos desde 1 de janeiro de 1970 UTC, seguindo a norma RFC 3339. Por exemplo, sexta-feira, 1 de setembro de 2023, 12:00:00 GMT é representado como 1693569600000. Isto aplica-se 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 tiver terminado, esta propriedade será 0.
Name
status
Type
string
Description
Estado 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, este contém apenas um objeto de URL de textura. Cada URL de textura tem as seguintes propriedades:
- Name
  base_color
  Type
  string
  Description
  URL para download 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-6-lite, meshy-7.1, meshy-t2, ou latest, esta propriedade será omitida.
Name
preceding_tasks
Type
integer
Description
A contagem de tarefas precedentes.
O valor deste campo só é relevante se o estado da tarefa for PENDING.
Name
task_error
Type
object
Description
Detalhes de erro para tarefas falhadas. 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 estado da tarefa é PENDING, IN_PROGRESS, ou SUCCEEDED. Devolve 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).

Example Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "texture_image_url": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}