UV Unwrap API

Generera en UV-uppveckling för en befintlig 3D-modell. Kör den innan du texturerar modellen, eller när ett verktyg som Blender, Substance Painter eller Unreal behöver en ren UV-layout utan överlapp.

Resultatet är en UV-vitmodell. Den har samma form som indatan, nya UV-koordinater och ingen riktig textur. Den innehåller ett 2×2 grått platshållarmaterial så att glTF-materialplatsen förblir giltig, och standardverktyg behandlar den som otexturerad.

UV Unwrap stöder nät med upp till 40 000 ytor. En större modell returnerar 400. För att minska antalet ytor, kör Remesh först.

Meshy triangulerar nät med fyrhörningar och n-hörningar under UV-genereringen, så resultatet är alltid ett triangelnät.

POST/openapi/v1/uv-unwrap

Skapa en UV-uppvecklingsuppgift

Skapar en UV-uppvecklingsuppgift.

Uppgiften körs i bakgrunden. För hur lång tid en uppgift vanligtvis tar, se Bearbetningstider.

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

Parametrar

Name
input_task_id
Type
string
Obligatorisk
Description
Krävs om du inte skickar model_url. ID:t för en Meshy API-uppgift vars GLB-utdata du vill veckla upp, till exempel en Bild till 3D-, Text till 3D- eller Remesh-uppgift. Uppgiften måste ha statusen SUCCEEDED och ha genererat en GLB-fil.
Nätet kan ha som mest 40 000 ytor (faces). Ett nät med fler returnerar 400. För att minska antalet ytor, kör Remesh först.

Name
model_url
Type
string
Obligatorisk
Description
Krävs om du inte skickar input_task_id. Modellen som ska vecklas upp, som en offentlig URL eller en Data URI. Om du skickar båda använder Meshy input_task_id.
Modellen måste vara en .glb-fil. För att veckla upp ett annat format, konvertera den till GLB med Convert API först.
Filen kan vara som mest 400 MB från en http- eller https-URL, eller 100 MB som en Data URI. För en Data URI, använd MIME type application/octet-stream. En GLB över 100 MB får inte använda Draco-komprimering.
Samma gräns på 40 000 ytor gäller som för input_task_id. Ett nät med fler returnerar 400, så kör Remesh först.

Returvärden

Fältet result i svaret innehåller ID:t för den nya UV-uppvecklingsuppgiften.

Felscenarier

Name
400 - Bad Request
Description
Begäran kan inte köras. Felmeddelandet anger vilket problem som hittades. Till exempel:
- Saknad parameter: Varken input_task_id eller model_url skickades.
- Ogiltig indatauppgift: input_task_id är inte en lyckad API-uppgift med ett GLB-resultat.
- Antal ytor överskridet: Nätet har fler ytor än vad UV-uppveckling tillåter. Kör Remesh först.
- Ogiltigt modellformat: Filen i model_url har en filändelse som inte stöds.
- Oåtkomlig URL: Meshy kan inte ladda ner filen i model_url.
- Modellfilen för stor: Filen i model_url är över 400 MB från en http- eller https-URL, eller över 100 MB som en Data URI.
- För många ytor: Filen i model_url är över 100 MB och har fler än 10 000 000 ytor. Minska antalet ytor och skicka sedan filen igen.
- Modellfil kan inte läsas: Filen i model_url är över 100 MB, och Meshy kan inte läsa dess header. Till exempel är den en Draco-komprimerad GLB.
- Modellheader för komplex: Filen i model_url är över 100 MB, och dess header har för många nät, noder eller poster att kontrollera. Minska antalet objekt i filen och skicka den sedan igen.
Åtgärda begäran och skicka den sedan igen. Se Fel.
Name
401 - Unauthorized
Description
API-nyckeln saknas eller är ogiltig. Kontrollera Authorization-headern.
Name
402 - Payment Required
Description
Till exempel:
- Otillräckliga credits: Kontot har inte tillräckligt med credits för den här uppgiften, eller kontot har nått en creditgräns. En UV-uppvecklingsuppgift kostar 5 credits. Kontrollera ditt credit-saldo och försök igen.
- Gratisplan: Att skapa en uppgift kräver en betald plan. Uppgradera din plan i dina prenumerationsinställningar och försök igen.
Name
403 - Forbidden
Description
input_task_id är en basreliefmodell, som denna endpoint inte kan veckla upp. Meddelandet är This model type does not support this operation. Skicka en annan modell.
Name
404 - Not Found
Description
input_task_id matchar ingen av dina uppgifter. Kontrollera uppgifts-ID:t och skicka sedan begäran igen.
Name
429 - Too Many Requests
Description
Du har överskridit din hastighetsgräns. Vänta och försök sedan igen. Se Hastighetsgränser.

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

Hämta en UV-uppveckling-uppgift

Returnerar en UV-uppveckling-uppgifts aktuella status baserat på dess 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}"

För ett exempel på svar, se exemplet på UV-uppveckling-uppgiftsobjektet.

Returnerar

UV-uppveckling-uppgiftsobjektet.

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

Ta bort en UV-uppvecklingsuppgift

Tar permanent bort en UV-uppvecklingsuppgift, inklusive dess utdata. Du kan inte ångra en borttagning.

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

Uppgiftsstatus

Att ta bort en uppgift med status PENDING återbetalar de credits som användes när du skapade den.

En uppgift med status IN_PROGRESS kan inte tas bort. Begäran returnerar 409 Conflict, och uppgiften fortsätter att köras. Meshy återbetalar inte en uppgift som har påbörjats, så att ta bort den skulle kosta dig både credits och resultatet. Vänta tills den når SUCCEEDED, FAILED eller CANCELED, och ta sedan bort den.

Att ta bort en uppgift med slutlig status (SUCCEEDED, FAILED eller CANCELED) ger ingen återbetalning av dess credits.

GET/openapi/v1/uv-unwrap

Lista UV-uppveckling-uppgifter

Returnerar en paginerad lista över dina UV-uppveckling-uppgifter, senaste först. För att bläddra igenom listan, använd page_num och 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

Strömma en UV-uppvecklingsuppgift

Strömmar uppdateringar för en UV-uppvecklingsuppgift som Server-Sent Events (SSE). Varje message-händelse innehåller ett UV-uppvecklingsuppgift-objekt. Strömmen stängs när uppgiften når SUCCEEDED, FAILED eller CANCELED.

För att snabbare få reda på att uppgiften är klar, använd denna endpoint istället för att polla 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

UV Unwrap-uppgiftsobjektet

Ett UV Unwrap-uppgiftsobjekt beskriver en UV-uppveckling av en 3D-modell. Det innehåller status, progress och modellfilen när uppgiften lyckas.

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
Uppgifts-ID:t. Behandla det som en opak sträng och förlita dig inte på dess format.
Name
type
Type
string
Description
Uppgiftstypen, alltid uv-unwrap.
Name
model_urls
Type
object
Description
Signerade nedladdningslänkar för UV-vitmodellen. UV Unwrap returnerar alltid en enda glb-nyckel. Modellen behåller den inmatade geometrin, har nya UV-koordinater och använder ett standardgrått material istället för en textur.
Name
thumbnail_url
Type
string
Description
Signerad nedladdningslänk för en PNG-förhandsgranskningsbild av UV-vitmodellen.
Name
progress
Type
integer
Description
Hur mycket av uppgiften som är klar, som en procentandel från 0 till 100.
Name
status
Type
string
Description
Uppgiftsstatusen, en av PENDING, IN_PROGRESS, SUCCEEDED, FAILED eller CANCELED.
Name
preceding_tasks
Type
integer
Description
Antalet uppgifter före denna i kön. Finns med medan uppgiften är PENDING.
Name
created_at
Type
timestamp
Description
Tidpunkten då uppgiften skapades, i Unix-millisekunder.
Name
started_at
Type
timestamp
Description
Tidpunkten då uppgiften startade, i Unix-millisekunder. Den är 0 tills uppgiften startar.
Name
finished_at
Type
timestamp
Description
Tidpunkten då uppgiften avslutades, i Unix-millisekunder. Den är 0 tills uppgiften avslutas.
Name
expires_at
Type
timestamp
Description
Tidpunkten då de signerade nedladdningslänkarna upphör att gälla, i Unix-millisekunder.
Name
task_error
Type
object
Description
Feldetaljerna när uppgiften misslyckas. Se Fel.
Name
consumed_credits
Type
integer
Description
Antalet credits uppgiften förbrukade. En lyckad UV Unwrap-uppgift kostar 5 credits. Den är 0 för en FAILED-uppgift, eftersom Meshy återbetalar credits när en uppgift misslyckas.