UV Unwrap API

Erzeuge eine UV-Entfaltung für ein vorhandenes 3D-Modell. Führe sie aus, bevor du das Modell texturierst, oder wenn ein Tool wie Blender, Substance Painter oder Unreal ein sauberes, überlappungsfreies UV-Layout benötigt.

Die Ausgabe ist ein UV-Weißmodell. Es hat die gleiche Form wie die Eingabe, neue UV-Koordinaten und keine echte Textur. Es enthält ein 2×2 graues Platzhaltermaterial, damit der glTF-Material-Slot gültig bleibt, und Standardtools behandeln es als untexturiert.

UV Unwrap unterstützt Netze mit bis zu 40.000 Flächen. Ein größeres Modell liefert 400 zurück. Um die Flächenanzahl zu reduzieren, führe zuerst Remesh aus.

Meshy trianguliert Quad- und N-Gon-Netze während der UV-Generierung, sodass die Ausgabe immer ein Dreiecksnetz ist.

POST/openapi/v1/uv-unwrap

Erstellen einer UV-Entfaltung-Aufgabe

Erstellt eine UV-Entfaltung-Aufgabe.

Die Aufgabe läuft im Hintergrund. Wie lange eine Aufgabe in der Regel dauert, erfahren Sie unter Verarbeitungszeiten.

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

Parameter

Name
input_task_id
Type
string
Erforderlich
Description
Erforderlich, sofern Sie nicht model_url senden. Die ID einer Meshy-API-Aufgabe, deren GLB-Ausgabe Sie entfalten möchten, zum Beispiel eine Bild-zu-3D-, Text-zu-3D- oder Neuvernetzung-Aufgabe. Die Aufgabe muss den Status SUCCEEDED haben und eine GLB-Datei erzeugt haben.
Das Netz kann höchstens 40.000 Flächen haben. Ein Netz mit mehr Flächen liefert 400. Um die Flächenanzahl zu reduzieren, führen Sie zuerst Neuvernetzung aus.

Name
model_url
Type
string
Erforderlich
Description
Erforderlich, sofern Sie nicht input_task_id senden. Das zu entfaltende Modell, als öffentliche URL oder als Data URI. Wenn Sie beides senden, verwendet Meshy input_task_id.
Das Modell muss eine .glb-Datei sein. Um ein anderes Format zu entfalten, konvertieren Sie es zuerst mit der Convert API in GLB.
Die Datei darf höchstens 400 MB groß sein, wenn sie von einer http- oder https-URL stammt, oder 100 MB als Data URI. Verwenden Sie für eine Data URI den MIME-Typ application/octet-stream. Eine GLB-Datei über 100 MB darf keine Draco-Komprimierung verwenden.
Es gilt dasselbe Limit von 40.000 Flächen wie bei input_task_id. Ein Netz mit mehr Flächen liefert 400, führen Sie also zuerst eine Neuvernetzung aus.

Rückgabewerte

Das Feld result der Antwort enthält die ID der neuen UV-Entfaltung-Aufgabe.

Fehlermodi

Name
400 - Bad Request
Description
Die Anfrage kann nicht ausgeführt werden. Die Fehlermeldung gibt an, welches Problem gefunden wurde. Zum Beispiel:
- Fehlender Parameter: Weder input_task_id noch model_url wurde gesendet.
- Ungültige Eingabeaufgabe: input_task_id ist keine erfolgreiche API-Aufgabe mit einem GLB-Ergebnis.
- Flächenanzahl überschritten: Das Netz hat mehr Flächen, als UV-Entfaltung zulässt. Führen Sie zuerst Neuvernetzung aus.
- Ungültiges Modellformat: Die Datei unter model_url hat eine nicht unterstützte Dateiendung.
- Nicht erreichbare URL: Meshy kann die Datei unter model_url nicht herunterladen.
- Modelldatei zu groß: Die Datei unter model_url ist größer als 400 MB bei einer http- oder https-URL, oder größer als 100 MB als Data URI.
- Zu viele Flächen: Die Datei unter model_url ist größer als 100 MB und hat mehr als 10.000.000 Flächen. Reduzieren Sie die Flächenanzahl und senden Sie die Datei erneut.
- Nicht lesbare Modelldatei: Die Datei unter model_url ist größer als 100 MB, und Meshy kann den Header nicht lesen. Zum Beispiel handelt es sich um eine Draco-komprimierte GLB-Datei.
- Modell-Header zu komplex: Die Datei unter model_url ist größer als 100 MB, und ihr Header enthält zu viele Netze, Knoten oder Einträge zum Prüfen. Reduzieren Sie die Anzahl der Objekte in der Datei und senden Sie sie erneut.
Beheben Sie die Anfrage und senden Sie sie erneut. Siehe Fehler.
Name
401 - Unauthorized
Description
Der API-Schlüssel fehlt oder ist ungültig. Überprüfen Sie den Authorization-Header.
Name
402 - Payment Required
Description
Zum Beispiel:
- Unzureichendes Guthaben: Das Konto verfügt nicht über genügend Credits für diese Aufgabe, oder das Konto hat ein Credit-Limit erreicht. Eine UV-Entfaltung-Aufgabe kostet 5 Credits. Prüfen Sie Ihr Credit-Guthaben und versuchen Sie es erneut.
- Kostenloser Plan: Das Erstellen einer Aufgabe erfordert einen kostenpflichtigen Plan. Aktualisieren Sie Ihren Plan in den Abonnement-Einstellungen und versuchen Sie es erneut.
Name
403 - Forbidden
Description
input_task_id ist ein Flachrelief-Modell, das dieser Endpunkt nicht entfalten kann. Die Meldung lautet This model type does not support this operation. Senden Sie ein anderes Modell.
Name
404 - Not Found
Description
input_task_id stimmt mit keiner Ihrer Aufgaben überein. Überprüfen Sie die Aufgaben-ID und senden Sie die Anfrage erneut.
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten. Warten Sie und versuchen Sie es erneut. Siehe Ratenbegrenzungen.

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

Eine UV-Entfaltungsaufgabe abrufen

Gibt den aktuellen Status einer UV-Entfaltungsaufgabe anhand ihrer ID zurück.

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

Ein Beispiel für eine Antwort finden Sie unter Beispiel für ein UV-Entfaltungsaufgabe-Objekt.

Rückgabewerte

Das UV-Entfaltungsaufgabe-Objekt.

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

Eine UV-Entfaltung-Aufgabe löschen

Löscht eine UV-Entfaltung-Aufgabe dauerhaft, einschließlich ihrer Ausgaben. Eine Löschung kann nicht rückgängig gemacht werden.

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

Aufgabenstatus

Das Löschen einer Aufgabe mit dem Status PENDING erstattet die Credits zurück, die beim Erstellen verwendet wurden.

Eine Aufgabe mit dem Status IN_PROGRESS kann nicht gelöscht werden. Die Anfrage gibt 409 Conflict zurück, und die Aufgabe läuft weiter. Meshy erstattet keine Credits für eine bereits gestartete Aufgabe, daher würde Sie das Löschen sowohl die Credits als auch das Ergebnis kosten. Warten Sie, bis der Status SUCCEEDED, FAILED oder CANCELED erreicht ist, und löschen Sie die Aufgabe dann.

Das Löschen einer Aufgabe mit einem endgültigen Status (SUCCEEDED, FAILED oder CANCELED) erstattet ihre Credits nicht zurück.

GET/openapi/v1/uv-unwrap

UV-Entfaltung-Aufgaben auflisten

Gibt eine paginierte Liste Ihrer UV-Entfaltung-Aufgaben zurück, die neuesten zuerst. Um durch die Liste zu blättern, verwenden Sie 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

Einen UV-Entfaltungs-Task streamen

Streamt die Updates eines UV-Entfaltungs-Tasks als Server-Sent Events (SSE). Jedes message-Event enthält ein UV-Entfaltungs-Task-Objekt. Der Stream wird geschlossen, sobald der Task den Status SUCCEEDED, FAILED oder CANCELED erreicht.

Um frühzeitig zu erfahren, dass der Task abgeschlossen ist, verwenden Sie diesen Endpunkt anstelle von wiederholtem Abfragen (Polling) von 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

Das UV-Entfaltung-Task-Objekt

Ein UV-Entfaltung-Task-Objekt beschreibt eine UV-Entfaltung eines 3D-Modells. Es enthält den Status, den progress und die Modelldatei, wenn der Task erfolgreich abgeschlossen wird.

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
Die Task-ID. Behandeln Sie sie als eine undurchsichtige Zeichenfolge und verlassen Sie sich nicht auf ihr Format.
Name
type
Type
string
Description
Der Task-Typ, immer uv-unwrap.
Name
model_urls
Type
object
Description
Signierte Download-URLs für das UV-Weißmodell. UV-Entfaltung gibt immer einen einzelnen glb-Schlüssel zurück. Das Modell behält die Eingabe-Geometrie bei, erhält neue UV-Koordinaten und verwendet ein standardmäßiges graues Material anstelle einer Textur.
Name
thumbnail_url
Type
string
Description
Signierte Download-URL für ein PNG-Vorschaubild des UV-Weißmodells.
Name
progress
Type
integer
Description
Wie viel des Tasks abgeschlossen ist, als Prozentsatz von 0 bis 100.
Name
status
Type
string
Description
Der Task-Status, einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED oder CANCELED.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der Tasks, die in der Warteschlange vor diesem liegen. Vorhanden, solange der Task PENDING ist.
Name
created_at
Type
timestamp
Description
Zeitpunkt der Erstellung des Tasks, in Unix-Millisekunden.
Name
started_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task gestartet wurde, in Unix-Millisekunden. Der Wert ist 0, bis der Task startet.
Name
finished_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task beendet wurde, in Unix-Millisekunden. Der Wert ist 0, bis der Task beendet ist.
Name
expires_at
Type
timestamp
Description
Zeitpunkt, zu dem die signierten Download-URLs ablaufen, in Unix-Millisekunden.
Name
task_error
Type
object
Description
Die Fehlerdetails, wenn der Task fehlschlägt. Siehe Fehler.
Name
consumed_credits
Type
integer
Description
Die Anzahl der Credits, die der Task verbraucht hat. Ein erfolgreicher UV-Entfaltung-Task kostet 5 Credits. Bei einem FAILED-Task ist der Wert 0, da Meshy die Credits erstattet, wenn ein Task fehlschlägt.