API de Desdobramento UV

A API de Desdobramento UV gera automaticamente um desdobramento UV de alta qualidade para um modelo 3D existente. Use-a como a etapa pré-requisito antes de texturizar — ou sempre que precisar de um layout UV limpo e sem sobreposições para ferramentas subsequentes (Blender, Substance Painter, Unreal).

A saída é um "modelo branco UV" — mesma forma que a entrada, mas com novas coordenadas UV e sem textura real (um material de espaço reservado cinza 2×2 é incluído para manter o slot de material glTF válido; ferramentas padrão tratam isso como não texturizado).

Limitações. O Auto UV atualmente suporta malhas de até 40.000 faces — modelos maiores são rejeitados com um 400; execute Remesh primeiro para reduzir a contagem de polígonos. Malhas de quad e n-gon são trianguladas durante a geração UV, então a saída é sempre uma malha de triângulos.

POST/openapi/v1/uv-unwrap

Criar uma Tarefa de Desdobramento UV

Este endpoint cria uma nova tarefa de Desdobramento UV.

Parâmetros

Exatamente um de input_task_id ou model_url é necessário. Se ambos forem fornecidos, input_task_id tem prioridade.

Name
input_task_id
Type
string
Obrigatório
Description
O ID de uma tarefa concluída da Meshy API cujo resultado GLB você deseja desdobrar em UV (por exemplo, um resultado de Imagem para 3D, Texto para 3D ou Remesh). A tarefa de origem deve ter status SUCCEEDED e ter produzido um arquivo GLB.
Se a malha de origem exceder o limite de contagem de faces de 40.000 faces, a solicitação será rejeitada com um 400 e você deve executar Remesh primeiro para reduzir a contagem de polígonos.

Name
model_url
Type
string
Obrigatório
Description
Forneça um modelo 3D diretamente através de uma URL publicamente acessível ou Data URI. Apenas .glb é suportado — a API lê binário glTF e não analisa outros formatos. Para desdobrar em UV um modelo em outro formato (.fbx, .obj, .stl, .gltf), converta-o para .glb primeiro através da Convert API, depois passe o ID da tarefa resultante como input_task_id ou sua URL de saída GLB aqui.
Para Data URIs, use o MIME type application/octet-stream.
O mesmo limite de 40.000 faces se aplica como para input_task_id: malhas superdimensionadas são rejeitadas com um 400 — execute Remesh primeiro.

Retornos

A propriedade result da resposta contém o id da nova tarefa de Desdobramento UV criada.

Modos de Falha

Name
400 - Bad Request
Description
A solicitação foi inaceitável. Causas comuns:
- Parâmetro ausente: Ou input_task_id ou model_url deve ser fornecido.
- Tarefa de entrada inválida: O input_task_id deve se referir a uma tarefa bem-sucedida com um resultado GLB.
- Contagem de faces excedida: A malha de origem tem mais faces do que o limite de Desdobramento UV. Execute Remesh primeiro.
- Formato de modelo inválido: O model_url aponta para um arquivo com uma extensão não suportada.
- URL inacessível: O model_url não pôde ser baixado.
Name
401 - Unauthorized
Description
A autenticação falhou. Por favor, verifique sua chave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarefa. Desdobramento UV custa 5 créditos por chamada.
Name
404 - Not Found
Description
O recurso não está habilitado para sua conta. Desdobramento UV é controlado por um sinalizador Statsig durante a implementação — entre em contato com o suporte Meshy se precisar de acesso.
Name
429 - Too Many Requests
Description
Você excedeu seu limite de taxa.

Request

POST

/openapi/v1/uv-unwrap

# Chain from an existing Meshy task
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "input_task_id": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
    }'

# Or from a publicly accessible model URL
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "model_url": "https://example.com/path/to/model.glb"
    }'

Response

{
  "result": "019361c6-9b34-7b23-bef2-d0107c4d92e2"
}

GET/openapi/v1/uv-unwrap/:id

Recuperar uma Tarefa de Desdobramento UV

Este endpoint recupera o estado atual de uma tarefa de Desdobramento UV por ID.

Retornos

Retorna um objeto de Tarefa de Desdobramento UV.

Request

GET

/openapi/v1/uv-unwrap/:id

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Veja o exemplo de objeto de tarefa abaixo.

DELETE/openapi/v1/uv-unwrap/:id

Excluir uma tarefa de Desdobramento UV

Exclui permanentemente uma tarefa de Desdobramento UV. A tarefa e suas saídas se tornam inacessíveis.

Uma tarefa que ainda está PENDING é excluída e os créditos consumidos no momento da criação são reembolsados.

Uma tarefa que já está IN_PROGRESS não pode ser excluída: a solicitação é rejeitada com 409 Conflict e a tarefa continua em execução. Os créditos de uma tarefa que o worker já começou não são reembolsáveis, então excluí-la no meio da execução custaria tanto os créditos quanto o resultado. Aguarde até que ela alcance SUCCEEDED, FAILED ou CANCELED, e então exclua-a.

Uma tarefa em um estado terminal (SUCCEEDED, FAILED ou CANCELED) é excluída sem reembolso.

Request

DELETE

/openapi/v1/uv-unwrap/:id

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/uv-unwrap

Listar Tarefas de Desdobramento UV

Retorna uma lista paginada das tarefas de Desdobramento UV do solicitante, da mais recente para a mais antiga. Paginação padrão via page_num e page_size.

Request

GET

/openapi/v1/uv-unwrap

curl "https://api.meshy.ai/openapi/v1/uv-unwrap?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/uv-unwrap/:id/stream

Transmitir uma Tarefa de Desdobramento UV

Inscreva-se no progress da tarefa como Eventos Enviados pelo Servidor. Cada evento message carrega um objeto de Tarefa de Desdobramento UV; o fluxo fecha assim que a tarefa atinge SUCCEEDED, FAILED ou CANCELED.

Use isso em vez de consultar GET /openapi/v1/uv-unwrap/:id para menor latência na conclusão.

Request

GET

/openapi/v1/uv-unwrap/:id/stream

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-N

O Objeto de Tarefa de Desdobramento UV

Name
id
Type
string
Description
Identificador único para a tarefa.
Name
type
Type
string
Description
Sempre uv-unwrap.
Name
model_urls
Type
object
Description
URLs de download pré-assinadas para o modelo branco UV gerado. O Desdobramento UV sempre retorna uma única entrada glb — a saída preserva a geometria de entrada, substitui por novas coordenadas UV e usa um material cinza padrão no lugar de qualquer textura.
Name
thumbnail_url
Type
string
Description
URL pré-assinada para uma pré-visualização PNG do modelo branco UV.
Name
progress
Type
integer
Description
Progresso da tarefa, de 0 a 100.
Name
status
Type
string
Description
Um de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
preceding_tasks
Type
integer
Description
Número de tarefas na fila antes desta. Presente enquanto o status é PENDING.
Name
created_at
Type
timestamp
Description
Carimbo de data/hora da criação da tarefa, em milissegundos.
Name
started_at
Type
timestamp
Description
Carimbo de data/hora de quando o processamento começou, em milissegundos. 0 até começar.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora de conclusão, em milissegundos. 0 até terminar.
Name
expires_at
Type
timestamp
Description
Carimbo de data/hora após o qual as URLs de download assinadas expiram, em milissegundos.
Name
task_error
Type
object
Description
Detalhes do erro para tarefas falhas. Veja Erros para a referência completa do objeto task_error.
Name
consumed_credits
Type
integer
Description
Créditos consumidos por esta tarefa. Retorna 0 para tarefas FAILED (créditos são reembolsados em caso de falha). O Desdobramento UV cobra 5 créditos em caso de sucesso.

Exemplo de Objeto de Tarefa de Desdobramento UV

{
  "id": "019361c6-9b34-7b23-bef2-d0107c4d92e2",
  "type": "uv-unwrap",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1716579120000,
  "started_at": 1716579122000,
  "finished_at": 1716579180000,
  "expires_at": 1716665580000,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 5
}