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

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ê quer usar como entrada. A tarefa precisa ter sido criada por você com a API, ter o status SUCCEEDED e 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 os dois, a Meshy usa input_task_id.
A imagem precisa ser um arquivo JPG, JPEG, PNG ou WebP de no máximo 20 MB.

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, a 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
Os modelos Smart Topology (model_type: smart-topology) produzem triângulos, com uma contagem de faces que você pode definir com target_polycount:
- meshy-t2: topologia mais limpa e peças nativamente separadas
- meshy-t2.5 (padrão): detalhe mais nítido para assets de jogos
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 requer meshy-7.1, latest ou o obsoleto meshy-7. 4k requer 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 pula a texturização e retorna uma malha sem textura.

Aplica-se somente quando should_texture = true

Name
enable_pbr
Type
boolean
padrão false
Description
Se também deve 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 meshy-6, a Meshy também gera um mapa de emissão, exceto em texture_resolution: 8k. Estes modelos não produzem um mapa de emissão:
- meshy-6-lite
- meshy-7
- meshy-7.1
- meshy-t2
- meshy-t2.5
- latest
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 não estão disponíveis com meshy-6-lite, e retornam 400 com ele. Em 8k, a 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 os dois, a 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.
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 precisa ser um arquivo JPG, JPEG, PNG ou WebP de no máximo 20 MB.
A Meshy guia a textura usando apenas um entre texture_prompt e texture_image_url. Se você enviar os dois, a Meshy usa texture_prompt. Para o custo em créditos da texturização, consulte Preços.
A texturização a partir de uma imagem pode não funcionar bem quando a forma da imagem difere muito da geometria do modelo 3D.

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 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 remesh.
Valores disponíveis:
- quad: uma malha predominantemente de quadriláteros
- triangle: uma malha de triângulos decimada
A saída do Smart Topology é apenas em triângulos, então quad com meshy-t2 ou meshy-t2.5 retorna 400.
Name
decimation_mode
Type
integer
Description
Contagem de faces adaptativa, por nível. Quando você o define, a Meshy ignora target_polycount.
Valores disponíveis:
- 1: ultra
- 2: alto
- 3: médio
- 4: baixo
Name
save_pre_remeshed_model
Type
boolean
padrão false
Description
Se também deve armazenar um GLB do modelo de antes da fase de remesh. A Meshy o retorna em model_urls.pre_remeshed_glb.

Name
target_polycount
Type
integer
Description
O número de faces desejado. O resultado pode diferir da meta, dependendo da geometria do modelo.
Isso se aplica em dois casos distintos:
- Remesh: Quando should_remesh é true em um modelo standard, a Meshy decima a malha para aproximadamente essa contagem. Se você definir decimation_mode, a Meshy o usa e ignora target_polycount.
- Smart Topology: Quando model_type é smart-topology e ai_model é meshy-t2 ou meshy-t2.5, a 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:
Caso Intervalo Padrão
Remesh 100 a 300000 30000
meshy-t2 100 a 15000 4000
meshy-t2.5 100 a 30000 15000
Um valor fora do intervalo retorna 400.

Caso	Intervalo	Padrão
Remesh	`100` a `300000`	`30000`
`meshy-t2`	`100` a `15000`	`4000`
`meshy-t2.5`	`100` a `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ obsoleto
padrão auto
Description
Deixe de fora, 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
padrão ""
Description
A pose para o modelo gerado.
Valores disponíveis:
- a-pose: uma pose em A
- t-pose: uma pose em T
- "" (string vazia): nenhuma pose específica
Name
is_a_t_pose
Type
boolean
⚠ obsoleto
padrão false
Description
Use pose_mode em vez disso. Se deve gerar o modelo em uma pose em A ou em T.
Name
surface_mode
Type
string
⚠ obsoleto
Description
Use ai_model em vez disso. Não afeta a saída, pois o modelo de geração que ele selecionava foi descontinuado.
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 a aparência exata da imagem de entrada, sem nenhum 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 meshy-6. meshy-7.1 e latest o aceitam e o ignoram. Com meshy-6-lite ou model_type: smart-topology, retorna 400.
Name
moderation
Type
boolean
padrão false
Description
Se deve verificar essas entradas em busca de conteúdo prejudicial antes de gerar:
- image_url
- texture_image_url
- texture_prompt
Se a Meshy detectar conteúdo prejudicial, a solicitação retorna 400 e a Meshy não cria a tarefa.
Name
target_formats
Type
string[]
Description
Os formatos de arquivo a serem gerados. A Meshy gera e retorna apenas os formatos que você listar, o que pode encurtar a tarefa. Se você deixar de fora, a Meshy gera todos os formatos, exceto 3mf, que você só recebe 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 com visão de IA e redimensionar o modelo para ela. A Meshy coloca a origem na parte inferior, a menos que você defina origin_at.
Name
alpha_thumbnail
Type
boolean
padrão false
Description
Se também deve renderizar uma pré-visualização 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 também deve renderizar pré-visualizações 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 solicitaçã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: A 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.
- Data URI inválido: A string em base64 está malformada.
- Combinação de parâmetros inválida: enable_pbr é true, e should_texture é false.
- Modelo não compatível com Ultra: geometry_resolution é 2k ou 4k, com um ai_model que não consegue executá-lo.
- Modelo não compatível com opções de imagem: image_enhancement ou remove_lighting foi enviado com ai_model: "meshy-6-lite" ou model_type: "smart-topology".
Corrija a solicitação e a envie 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 essa 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
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 o limite de taxa. Aguarde e tente novamente. Consulte Limites de taxa.

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

Get an Image to 3D task

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

Parâmetros

Name
id
Type
path
Description
O ID da tarefa retornado na resposta de criação.

Retorno

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

Parâmetros

Name
page_num
Type
integer
padrão 1
Description
O número da página a ser retornada. As páginas começam em 1.
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

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

Parâmetros

Name
id
Type
path
Description
O ID da tarefa retornado 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 progress 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": {
    "message": ""
  },
  "consumed_credits": 30
}

Name
id
Type
string
Description
O ID da tarefa. Trate-o como uma string opaca e não dependa de 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 para cada formato de arquivo. Um formato que a tarefa não gerou não possui 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 possui 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 512×512, renderizado com os mesmos materiais e iluminação de thumbnail_url. Use-as para pré-visualizar o modelo 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 chegou a SUCCEEDED. Tarefas criadas sem multi_view_thumbnails: true não incluem este 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_url
Type
string
Description
URL de download para a imagem que guiou a textura.
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, 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 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 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. O campo está ausente quando você criou a tarefa com enable_pbr: false ou texture_resolution: 8k, ou quando ai_model é um destes modelos:
  
  meshy-6-lite
  
  meshy-7
  
  meshy-7.1
  
  meshy-t2
  
  meshy-t2.5
  
  latest
Name
preceding_tasks
Type
integer
Description
O número de tarefas à frente desta na fila. O valor só é significativo enquanto a tarefa está PENDING.
Name
task_error
Type
object
Description
Os detalhes do erro quando a tarefa falha. 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, pois a Meshy reembolsa os créditos quando uma tarefa falha.