API de Desdobramento UV

A API de Desdobramento UV gera automaticamente um Desdobramento UV de alta qualidade para um modelo 3D existente. Utilize-a como o passo de pré-requisito antes da texturização — ou sempre que precisar de uma disposição UV limpa e sem sobreposições para ferramentas a jusante (Blender, Substance Painter, Unreal).

O resultado é um "modelo branco UV" — a mesma forma que a entrada, mas com coordenadas UV totalmente novas e sem textura real (é incluído um material de marcador de posição cinzento 2×2 para manter a ranhura de material glTF válida; as ferramentas padrão tratam isto como sem textura).

Limitações. O UV automático suporta atualmente malhas de até 40.000 faces — modelos maiores são rejeitados com um 400; execute primeiro o Remesh para reduzir a contagem de polígonos. Malhas quad e n-gon são trianguladas durante a geração UV, por isso o resultado é sempre uma malha triangular.

POST/openapi/v1/uv-unwrap

Criar uma tarefa de Desdobramento UV

Este endpoint cria uma nova tarefa de Desdobramento UV.

Parâmetros

É obrigatório fornecer exatamente um de input_task_id ou model_url. 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 pretende submeter a Desdobramento UV (por exemplo, um resultado de Imagem para 3D, Texto para 3D ou Remesh). A tarefa de origem deve ter o estado SUCCEEDED e ter produzido um ficheiro GLB.

    Se a malha de origem exceder o limite máximo de contagem de faces de 40 000 faces, o pedido será rejeitado com um 400 e deverá 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 um URL publicamente acessível ou de um Data URI. Apenas .glb é suportado — a API lê glTF binário e não analisa outros formatos. Para aplicar Desdobramento UV a um modelo noutro formato (.fbx, .obj, .stl, .gltf), converta-o primeiro para .glb através da API de Converter e, em seguida, passe o ID da tarefa resultante como input_task_id ou o respetivo URL de saída GLB aqui.

    Para Data URIs, utilize o MIME type application/octet-stream.

    Aplica-se o mesmo limite máximo de 40 000 faces que para input_task_id: malhas demasiado grandes são rejeitadas com um 400 — execute Remesh primeiro.

Devolve

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

Modos de falha

  • Name
    400 - Bad Request
    Description

    O pedido era inaceitável. Causas comuns:

    • Parâmetro em falta: É necessário fornecer input_task_id ou model_url.
    • Tarefa de entrada inválida: O input_task_id deve referir-se a uma tarefa bem-sucedida com um resultado GLB.
    • Contagem de faces excedida: A malha de origem tem mais faces do que o limite máximo de Desdobramento UV. Execute Remesh primeiro.
    • Formato de modelo inválido: O model_url aponta para um ficheiro com uma extensão não suportada.
    • URL inacessível: Não foi possível descarregar o model_url.
  • Name
    401 - Unauthorized
    Description

    A autenticação falhou. Verifique a sua chave de API.

  • Name
    402 - Payment Required
    Description

    Créditos insuficientes para executar esta tarefa. Desdobramento UV custa 5 créditos por chamada.

  • Name
    404 - Not Found
    Description

    A funcionalidade não está ativada na sua conta. Desdobramento UV está condicionado por uma flag Statsig durante a disponibilização gradual — contacte o apoio da Meshy se precisar de acesso.

  • Name
    429 - Too Many Requests
    Description

    Excedeu o 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

Obter uma tarefa de Desdobramento UV

Este endpoint obtém o estado atual de uma tarefa de Desdobramento UV por ID.

Devolve

Devolve 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}"

Consulte o objeto de tarefa de Desdobramento UV de exemplo abaixo.

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

Eliminar uma tarefa de Desdobramento UV

Elimine permanentemente uma tarefa de Desdobramento UV. A tarefa e os seus resultados ficam inacessíveis.

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

Devolve uma lista paginada das tarefas de Desdobramento UV do chamador, das mais recentes para as mais antigas. Paginação padrão através de 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 em streaming uma tarefa de Desdobramento UV

Subscreva o progress da tarefa como Server-Sent Events. Cada evento message transporta um objeto de Tarefa de Desdobramento UV; o stream fecha assim que a tarefa atinge SUCCEEDED, FAILED ou CANCELED.

Utilize isto em vez de consultar GET /openapi/v1/uv-unwrap/:id repetidamente para obter 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 da tarefa.

  • Name
    type
    Type
    string
    Description

    Sempre uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    URLs de transferência pré-assinados para o modelo branco UV gerado. O Desdobramento UV devolve sempre uma única entrada glb — a saída preserva a geometria de entrada, substitui-a por novas coordenadas UV e usa um material cinzento predefinido em vez de qualquer textura.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL pré-assinado para uma pré-visualização PNG do modelo branco UV.

  • Name
    progress
    Type
    integer
    Description

    progress 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 em fila antes desta. Presente enquanto o estado é 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 da conclusão, em milissegundos. 0 até terminar.

  • Name
    expires_at
    Type
    timestamp
    Description

    Carimbo de data/hora após o qual os URLs de transferência assinados expiram, em milissegundos.

  • Name
    task_error
    Type
    object
    Description

    Detalhes do erro para tarefas falhadas. Consulte Erros para a referência completa do objeto task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Créditos consumidos por esta tarefa. Devolve 0 para tarefas FAILED (os créditos são reembolsados em caso de falha). O Desdobramento UV cobra 5 créditos em caso de sucesso.

Example UV Unwrap Task Object

{
  "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
}