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 o Blender, o Substance Painter ou o Unreal precisar de uma disposição UV limpa e sem sobreposições.

O resultado é um modelo branco UV. Tem a mesma forma do modelo de entrada, novas coordenadas UV e nenhuma textura real. Inclui um material cinzento 2×2 de preenchimento para que a ranhura de material do glTF se mantenha válida, e as ferramentas padrão tratam-no como não texturizado.

O Desdobramento UV suporta malhas com até 40.000 faces. Um modelo maior devolve 400. Para reduzir o número de faces, execute primeiro o Remesh.

A Meshy triangula malhas quad e n-gon durante a geração UV, pelo que o resultado é sempre uma malha de triângulos.

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 normalmente demora, consulte 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 envie model_url. O ID de uma tarefa da Meshy API cujo resultado GLB pretende desdobrar, por exemplo uma tarefa de Imagem para 3D, Texto para 3D ou Remesh. A tarefa deve ter o estado SUCCEEDED e ter produzido um ficheiro GLB.
A malha pode ter no máximo 40 000 faces. Uma malha com mais faces devolve 400. Para reduzir o número de faces, execute primeiro Remesh.

Name
model_url
Type
string
Obrigatório
Description
Obrigatório, a menos que envie input_task_id. O modelo a desdobrar, como um URL público ou um Data URI. Se enviar ambos, a Meshy utiliza input_task_id.
O modelo deve ser um ficheiro .glb. Para desdobrar outro formato, converta-o primeiro para GLB com a Convert API.
O ficheiro pode ter no máximo 400 MB a partir de um URL http ou https, ou 100 MB como Data URI. Para um Data URI, utilize o MIME type application/octet-stream. Um GLB com mais de 100 MB não pode utilizar compressão Draco.
Aplica-se o mesmo limite de 40 000 faces que para input_task_id. Uma malha com mais faces devolve 400, pelo que deve executar primeiro o Remesh.

Devoluções

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

Modos de falha

Name
400 - Bad Request
Description
O pedido não pode ser executado. A mensagem de erro indica qual o problema encontrado. Por exemplo:
- Parâmetro em falta: Não foi enviado nem input_task_id nem model_url.
- Tarefa de entrada inválida: input_task_id não corresponde a uma tarefa da API bem-sucedida com um resultado GLB.
- Limite de faces excedido: A malha tem mais faces do que o permitido pelo Desdobramento UV. Execute primeiro Remesh.
- Formato de modelo inválido: O ficheiro model_url tem uma extensão não suportada.
- URL inacessível: A Meshy não consegue transferir o ficheiro model_url.
- Ficheiro de modelo demasiado grande: O ficheiro model_url tem mais de 400 MB a partir de um URL http ou https, ou mais de 100 MB como Data URI.
- Demasiadas faces: O ficheiro model_url tem mais de 100 MB e mais de 10 000 000 faces. Reduza o número de faces e envie o ficheiro novamente.
- Ficheiro de modelo ilegível: O ficheiro model_url tem mais de 100 MB, e a Meshy não consegue ler o seu cabeçalho. Por exemplo, é um GLB comprimido com Draco.
- Cabeçalho do modelo demasiado complexo: O ficheiro model_url tem mais de 100 MB, e o seu cabeçalho tem demasiadas malhas, nós ou registos para verificar. Reduza o número de objetos no ficheiro e envie-o novamente.
Corrija o pedido e envie-o novamente. Consulte Erros.
Name
401 - Unauthorized
Description
A chave de API está em falta 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 o seu saldo de créditos e tente novamente.
- Plano gratuito: Criar uma tarefa requer um plano pago. Atualize o seu plano nas definições de subscrição e tente novamente.
Name
403 - Forbidden
Description
input_task_id é um modelo de baixo-relevo, que este endpoint não consegue 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 o pedido novamente.
Name
429 - Too Many Requests
Description
Excedeu o seu limite de taxa. Aguarde e tente novamente. Consulte Limites de taxa.

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

Obter uma tarefa de Desdobramento UV

Devolve o estado atual de uma tarefa de Desdobramento UV através do 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.

Devolve

O objeto de tarefa de Desdobramento UV.

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

Eliminar uma tarefa de Desdobramento UV

Elimina permanentemente uma tarefa de Desdobramento UV, incluindo os seus resultados. Não é possível anular uma eliminaçã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}"

Estado da tarefa

Eliminar uma tarefa PENDING reembolsa os créditos que utilizou ao criá-la.

Uma tarefa IN_PROGRESS não pode ser eliminada. O pedido devolve 409 Conflict, e a tarefa continua em execução. A Meshy não reembolsa uma tarefa que já começou, pelo que eliminá-la custar-lhe-ia tanto os créditos como o resultado. Aguarde até que atinja o estado SUCCEEDED, FAILED ou CANCELED, e só depois a elimine.

Eliminar uma tarefa num estado final (SUCCEEDED, FAILED ou CANCELED) não reembolsa os seus créditos.

GET/openapi/v1/uv-unwrap

Listar tarefas de Desdobramento UV

Devolve uma lista paginada das suas tarefas de Desdobramento UV, começando pelas mais recentes. Para percorrer a 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

Fazer streaming de uma tarefa de Desdobramento UV

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

Para saber mais cedo que a tarefa terminou, utilize este endpoint em vez de fazer polling a 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 da tarefa Desdobramento UV

Um objeto da tarefa Desdobramento UV descreve um desdobramento UV de um modelo 3D. Contém o estado, o progress e o ficheiro 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 de tarefa, sempre uv-unwrap.
Name
model_urls
Type
object
Description
URLs de transferência assinados para o modelo branco UV. O Desdobramento UV devolve sempre uma única chave glb. O modelo mantém a geometria de entrada, tem novas coordenadas UV e usa um material cinzento predefinido em vez de uma textura.
Name
thumbnail_url
Type
string
Description
URL de transferência assinado para uma imagem de pré-visualização PNG do modelo branco UV.
Name
progress
Type
integer
Description
Quanto da tarefa está concluído, como percentagem de 0 a 100.
Name
status
Type
string
Description
O estado da tarefa, um de 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á PENDING.
Name
created_at
Type
timestamp
Description
Hora em que a tarefa foi criada, em milissegundos Unix.
Name
started_at
Type
timestamp
Description
Hora em que a tarefa foi iniciada, em milissegundos Unix. É 0 até a tarefa começar.
Name
finished_at
Type
timestamp
Description
Hora em que a tarefa terminou, em milissegundos Unix. É 0 até a tarefa terminar.
Name
expires_at
Type
timestamp
Description
Hora em que os URLs de transferência assinados 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 que a tarefa utilizou. Uma tarefa de Desdobramento UV bem-sucedida custa 5 créditos. É 0 para uma tarefa FAILED, porque a Meshy reembolsa os créditos quando uma tarefa falha.