UV-Entfaltung API

Die UV-Entfaltung API generiert automatisch eine hochwertige UV-Entfaltung für ein bestehendes 3D-Modell. Verwenden Sie es als Voraussetzungsschritt vor dem Texturieren – oder immer dann, wenn Sie ein sauberes, nicht überlappendes UV-Layout für nachgelagerte Tools (Blender, Substance Painter, Unreal) benötigen.

Das Ergebnis ist ein "UV-Weißmodell" – gleiche Form wie das Eingabemodell, aber mit brandneuen UV-Koordinaten und keiner echten Textur (ein 2×2 graues Platzhaltermaterial ist enthalten, um den glTF-Materialslot gültig zu halten; Standardtools behandeln dies als untexturiert).

Einschränkungen. Auto UV unterstützt derzeit Netze mit bis zu 40.000 Flächen – größere Modelle werden mit einem 400 abgelehnt; führen Sie zuerst eine Neuvernetzung durch, um die Polygonanzahl zu reduzieren. Quad- und N-Gon-Netze werden während der UV-Generierung trianguliert, sodass das Ergebnis immer ein Dreiecksnetz ist.

POST/openapi/v1/uv-unwrap

Create an UV Unwrap Task

Dieser Endpunkt erstellt eine neue UV-Entfaltung-Aufgabe.

Die Aufgabe läuft im Hintergrund. Wie lange dies üblicherweise dauert, erfahren Sie unter Processing Times.

Parameter

Genau eines von input_task_id oder model_url ist erforderlich. Werden beide angegeben, hat input_task_id Priorität.

Name
input_task_id
Type
string
Erforderlich
Description
Die ID einer abgeschlossenen Meshy API-Aufgabe, deren GLB-Ausgabe Sie per UV-Entfaltung bearbeiten möchten (zum Beispiel das Ergebnis von Bild zu 3D, Text zu 3D oder Neuvernetzung). Die Quellaufgabe muss den Status SUCCEEDED haben und eine GLB-Datei erzeugt haben.
Überschreitet das Quellnetz die Obergrenze von 40.000 Flächen, wird die Anfrage mit 400 abgelehnt, und Sie sollten zunächst eine Neuvernetzung durchführen, um die Polygonanzahl zu reduzieren.

Name
model_url
Type
string
Erforderlich
Description
Stellen Sie ein 3D-Modell direkt über eine öffentlich zugängliche URL oder einen Data URI bereit. Es wird nur .glb unterstützt — die API liest glTF-Binärdaten und analysiert keine anderen Formate. Um ein Modell in einem anderen Format (.fbx, .obj, .stl, .gltf) per UV-Entfaltung zu bearbeiten, konvertieren Sie es zunächst über die Convert API in .glb und übergeben Sie anschließend die resultierende Aufgaben-ID als input_task_id oder deren GLB-Ausgabe-URL hier.
Verwenden Sie für Data URIs den MIME-Typ application/octet-stream.
Maximale Dateigröße: 100 MB.
Es gilt dieselbe Obergrenze von 40.000 Flächen wie bei input_task_id: überdimensionierte Netze werden mit 400 abgelehnt — führen Sie zunächst eine Neuvernetzung durch.

Rückgabewerte

Die Eigenschaft result der Antwort enthält die id der neu erstellten UV-Entfaltung-Aufgabe.

Fehlermodi

Name
400 - Bad Request
Description
Die Anfrage war nicht akzeptabel. Häufige Ursachen:
- Fehlender Parameter: Entweder input_task_id oder model_url muss angegeben werden.
- Ungültige Eingabeaufgabe: input_task_id muss sich auf eine erfolgreiche Aufgabe mit einem GLB-Ergebnis beziehen.
- Flächenanzahl überschritten: Das Quellnetz hat mehr Flächen als die Obergrenze für die UV-Entfaltung. Führen Sie zunächst eine Neuvernetzung durch.
- Ungültiges Modellformat: model_url verweist auf eine Datei mit einer nicht unterstützten Erweiterung.
- Nicht erreichbare URL: model_url konnte nicht heruntergeladen werden.
- Modelldatei zu groß: Die Datei unter model_url überschreitet 100 MB.
Name
401 - Unauthorized
Description
Die Authentifizierung ist fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.
Name
402 - Payment Required
Description
Unzureichende Credits, um diese Aufgabe auszuführen. Eine UV-Entfaltung kostet 5 Credits pro Aufruf.
Name
404 - Not Found
Description
Die Funktion ist für Ihr Konto nicht aktiviert. Die UV-Entfaltung wird während der Einführung über ein Statsig-Flag freigeschaltet — wenden Sie sich an den Meshy-Support, falls Sie Zugriff benötigen.
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten.

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

Abrufen einer UV-Entfaltung-Aufgabe

Dieser Endpunkt ruft den aktuellen Status einer UV-Entfaltung-Aufgabe anhand der ID ab.

Rückgaben

Gibt ein UV-Entfaltung-Aufgabenobjekt zurück.

Anfrage

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

Siehe das Beispiel-Aufgabenobjekt unten.

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

Eine UV-Entfaltungs-Aufgabe löschen

Löscht eine UV-Entfaltungs-Aufgabe dauerhaft. Die Aufgabe und ihre Ausgaben werden unzugänglich.

Eine Aufgabe, die sich noch im Status PENDING befindet, wird gelöscht, und die bei der Erstellung verbrauchten Credits werden erstattet.

Eine Aufgabe, die sich bereits IN_PROGRESS befindet, kann nicht gelöscht werden: Die Anfrage wird mit 409 Conflict abgelehnt, und die Aufgabe läuft weiter. Credits für eine Aufgabe, die der Worker bereits gestartet hat, sind nicht erstattungsfähig. Ein Löschen mitten im Ablauf würde Sie also sowohl die Credits als auch das Ergebnis kosten. Warten Sie, bis sie SUCCEEDED, FAILED oder CANCELED erreicht, und löschen Sie sie dann.

Eine Aufgabe in einem Endzustand (SUCCEEDED, FAILED oder CANCELED) wird ohne Erstattung gelöscht.

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

UV-Entfaltungsaufgaben auflisten

Gibt eine paginierte Liste der UV-Entfaltungsaufgaben des Anrufers zurück, beginnend mit den neuesten. Standard-Paginierung über page_num und 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

Streamen einer UV-Entfaltung-Aufgabe

Abonnieren Sie den Fortschritt der Aufgabe als Server-Sent Events. Jedes message-Ereignis enthält ein UV-Entfaltung-Aufgabenobjekt; der Stream schließt, sobald die Aufgabe SUCCEEDED, FAILED oder CANCELED erreicht.

Verwenden Sie dies anstelle des Pollings von GET /openapi/v1/uv-unwrap/:id für eine geringere Latenzzeit bei der Fertigstellung.

Anfrage

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

Das UV-Entfaltung-Aufgabenobjekt

Name
id
Type
string
Description
Eindeutiger Bezeichner für die Aufgabe.
Name
type
Type
string
Description
Immer uv-unwrap.
Name
model_urls
Type
object
Description
Vorab signierte Download-URLs für das generierte UV-Weißmodell. UV-Entfaltung gibt immer einen einzelnen glb-Eintrag zurück — die Ausgabe bewahrt die Eingabegeometrie, tauscht frische UV-Koordinaten ein und verwendet ein standardmäßiges graues Material anstelle einer Textur.
Name
thumbnail_url
Type
string
Description
Vorab signierte URL zu einer PNG-Vorschau des UV-Weißmodells.
Name
progress
Type
integer
Description
Aufgabenfortschritt, von 0 bis 100.
Name
status
Type
string
Description
Einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
preceding_tasks
Type
integer
Description
Anzahl der Aufgaben, die vor dieser in der Warteschlange stehen. Vorhanden, während der Status PENDING ist.
Name
created_at
Type
timestamp
Description
Zeitstempel der Aufgabenerstellung, in Millisekunden.
Name
started_at
Type
timestamp
Description
Zeitstempel, wann die Verarbeitung begann, in Millisekunden. 0 bis zum Start.
Name
finished_at
Type
timestamp
Description
Zeitstempel der Fertigstellung, in Millisekunden. 0 bis zur Fertigstellung.
Name
expires_at
Type
timestamp
Description
Zeitstempel, nach dem die signierten Download-URLs ablaufen, in Millisekunden.
Name
task_error
Type
object
Description
Fehlerdetails für fehlgeschlagene Aufgaben. Siehe Fehler für die vollständige task_error-Objektreferenz.
Name
consumed_credits
Type
integer
Description
Credits, die von dieser Aufgabe verbraucht wurden. Gibt 0 für FAILED-Aufgaben zurück (Credits werden bei einem Fehler zurückerstattet). UV-Entfaltung berechnet 5 Credits bei Erfolg.

Beispiel UV-Entfaltung-Aufgabenobjekt

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