API de Desdobramento UV

Gere um desdobramento UV para um modelo 3D existente. Execute-o antes de texturizar o modelo, ou quando uma ferramenta como Blender, Substance Painter ou Unreal precisar de um layout UV limpo e sem sobreposições.

A saída é um modelo branco UV. Ele tem a mesma forma do modelo de entrada, novas coordenadas UV e nenhuma textura real. Inclui um material de espaço reservado cinza 2×2 para que o slot de material glTF permaneça válido, e ferramentas padrão o tratam como não texturizado.

O Desdobramento UV suporta malhas com até 40.000 faces. Um modelo maior retorna 400. Para reduzir a contagem de faces, execute o Remesh primeiro.

O Meshy triangula malhas de quadriláteros e n-gons durante a geração de UV, portanto a saída é sempre uma malha triangular.

POST/openapi/v1/uv-unwrap

Criar uma tarefa de Desdobramento UV

Cria uma tarefa de Desdobramento UV.

A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa geralmente leva, veja Tempos de processamento.

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

Parâmetros

Name
input_task_id
Type
string
Obrigatório
Description
Obrigatório, a menos que você envie model_url. O ID de uma tarefa da Meshy API cuja saída GLB você deseja desdobrar, por exemplo, uma tarefa de Imagem para 3D, Texto para 3D ou Remesh. A tarefa deve ter o status SUCCEEDED e ter produzido um arquivo GLB.
A malha pode ter no máximo 40.000 faces. Uma malha com mais faces retorna 400. Para reduzir a contagem de faces, execute Remesh primeiro.

Name
model_url
Type
string
Obrigatório
Description
Obrigatório, a menos que você envie input_task_id. O modelo a ser desdobrado, como uma URL pública ou um Data URI. Se você enviar ambos, a Meshy usa input_task_id.
O modelo deve ser um arquivo .glb. Para desdobrar outro formato, converta-o para GLB primeiro com a Convert API.
O arquivo pode ter no máximo 400 MB a partir de uma URL http ou https, ou 100 MB como Data URI. Para um Data URI, use o MIME type application/octet-stream. Um GLB com mais de 100 MB não deve usar compressão Draco.
Aplica-se o mesmo limite de 40.000 faces de input_task_id. Uma malha com mais faces retorna 400, portanto execute o Remesh primeiro.

Retornos

O campo result da resposta contém o ID da nova tarefa de Desdobramento UV.

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 input_task_id nem model_url foram enviados.
- Tarefa de entrada inválida: input_task_id não é uma tarefa de API bem-sucedida com um resultado GLB.
- Contagem de faces excedida: A malha tem mais faces do que o Desdobramento UV permite. Execute Remesh primeiro.
- Formato de modelo inválido: O arquivo em model_url tem uma extensão não suportada.
- URL inacessível: A Meshy não consegue baixar o arquivo de model_url.
- Arquivo de modelo muito grande: O arquivo em model_url tem mais de 400 MB a partir de uma URL http ou https, ou mais de 100 MB como Data URI.
- Muitas faces: O arquivo em model_url tem mais de 100 MB e mais de 10.000.000 de faces. Reduza a contagem de faces e envie o arquivo novamente.
- Arquivo de modelo ilegível: O arquivo em model_url tem mais de 100 MB, e a Meshy não consegue ler seu cabeçalho. Por exemplo, é um GLB comprimido com Draco.
- Cabeçalho do modelo muito complexo: O arquivo em model_url tem mais de 100 MB, e seu cabeçalho tem malhas, nós ou registros demais para verificar. Reduza o número de objetos no arquivo e envie-o novamente.
Corrija a requisição e envie-a novamente. Veja 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. Uma tarefa de Desdobramento UV custa 5 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
input_task_id é um modelo de baixo-relevo, que este endpoint não pode desdobrar. A mensagem é This model type does not support this operation. Envie um modelo diferente.
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. Veja Limites de taxa.

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

Obter uma tarefa de Desdobramento UV

Retorna o estado atual de uma tarefa de Desdobramento UV pelo seu ID.

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

Para ver um exemplo de resposta, consulte o exemplo de objeto de tarefa de Desdobramento UV.

Retornos

O objeto de tarefa de Desdobramento UV.

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

Delete a UV Unwrap task

Exclui permanentemente uma tarefa de Desdobramento UV, incluindo seus resultados. Você não pode desfazer uma exclusão.

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

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 solicitaçã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 para então excluí-la.

Excluir uma tarefa em um status final (SUCCEEDED, FAILED ou CANCELED) não reembolsa seus créditos.

GET/openapi/v1/uv-unwrap

Listar tarefas de Desdobramento UV

Retorna uma lista paginada das suas tarefas de Desdobramento UV, das mais recentes para as mais antigas. Para navegar pela lista, use 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 um stream de uma tarefa de Desdobramento UV

Transmite as atualizações de uma tarefa de Desdobramento UV como Server-Sent Events (SSE). Cada evento message carrega um objeto de tarefa de Desdobramento UV. O stream é encerrado quando a tarefa atinge SUCCEEDED, FAILED ou CANCELED.

Para saber mais rapidamente que a tarefa foi concluída, use este endpoint em vez de fazer polling em GET /openapi/v1/uv-unwrap/:id.

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

Um objeto de tarefa de Desdobramento UV descreve um desdobramento UV de um modelo 3D. Ele contém o status, o progress e o arquivo do modelo quando a tarefa é bem-sucedida.

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
}

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 uv-unwrap.
Name
model_urls
Type
object
Description
URLs de download assinadas para o modelo branco UV. O Desdobramento UV sempre retorna uma única chave glb. O modelo mantém a geometria de entrada, possui novas coordenadas UV e usa um material cinza padrão em vez de uma textura.
Name
thumbnail_url
Type
string
Description
URL de download assinada para uma imagem de pré-visualização PNG do modelo branco UV.
Name
progress
Type
integer
Description
O quanto da tarefa foi concluído, em porcentagem de 0 a 100.
Name
status
Type
string
Description
O status da tarefa, um dos seguintes: PENDING, IN_PROGRESS, SUCCEEDED, FAILED ou CANCELED.
Name
preceding_tasks
Type
integer
Description
O número de tarefas à frente desta na fila. Presente enquanto a tarefa está em PENDING.
Name
created_at
Type
timestamp
Description
Horário em que a tarefa foi criada, em milissegundos Unix.
Name
started_at
Type
timestamp
Description
Horário em que a tarefa foi iniciada, em milissegundos Unix. É 0 até a tarefa começar.
Name
finished_at
Type
timestamp
Description
Horário em que a tarefa foi concluída, em milissegundos Unix. É 0 até a tarefa terminar.
Name
expires_at
Type
timestamp
Description
Horário em que as URLs de download assinadas expiram, em milissegundos Unix.
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 usados pela tarefa. Uma tarefa de Desdobramento UV bem-sucedida custa 5 créditos. É 0 para uma tarefa FAILED, pois a Meshy reembolsa os créditos quando uma tarefa falha.