UV-Unwrap-API

Die UV-Unwrap-API generiert automatisch ein hochwertiges UV-Unwrap für ein vorhandenes 3D-Modell. Verwende sie als erforderlichen Schritt vor dem Texturieren — oder immer dann, wenn du ein sauberes, überlappungsfreies UV-Layout für nachgelagerte Tools benötigst (Blender, Substance Painter, Unreal).

Die Ausgabe ist ein „UV-Weißmodell“ — dieselbe Form wie die Eingabe, aber mit komplett neuen UV-Koordinaten und ohne echte texture (ein graues 2×2-Platzhaltermaterial ist enthalten, damit der glTF-Material-Slot gültig bleibt; Standard-Tools behandeln dies als untexturiert).

Einschränkungen. Auto UV unterstützt derzeit Meshes mit bis zu 40.000 Flächen — größere Modelle werden mit einem 400 abgelehnt; führe zuerst Remesh aus, um die Polygonanzahl zu reduzieren. Quad- und N-Gon-Meshes werden während der UV-Generierung trianguliert, daher ist die Ausgabe immer ein Dreiecksmesh.

POST/openapi/v1/uv-unwrap

Eine UV-Unwrap-Aufgabe erstellen

Dieser endpoint erstellt eine neue UV-Unwrap-Aufgabe.

Parameter

Genau einer der Parameter input_task_id oder model_url ist erforderlich. Wenn beide angegeben werden, hat input_task_id Vorrang.

  • Name
    input_task_id
    Type
    string
    Erforderlich
    Description

    Die ID einer abgeschlossenen Meshy-API-Aufgabe, deren GLB-Ausgabe Sie per UV-Unwrap abwickeln möchten (zum Beispiel ein Image-to-3D-, Text-to-3D- oder Remesh-Ergebnis). Die Quellaufgabe muss den Status SUCCEEDED haben und eine GLB-Datei erzeugt haben.

    Wenn das Quellmesh die Obergrenze von 40.000 Flächen überschreitet, wird die Anfrage mit einem 400 abgelehnt, und Sie sollten zuerst Remesh ausfü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 Daten-URI bereit. Nur .glb wird unterstützt — die API liest glTF Binary und parst keine anderen Formate. Um ein Modell in einem anderen Format (.fbx, .obj, .stl, .gltf) per UV-Unwrap abzuwickeln, konvertieren Sie es zuerst über die Convert API in .glb und übergeben Sie dann die resultierende Aufgaben-ID als input_task_id oder die zugehörige GLB-Ausgabe-URL hier.

    Verwenden Sie für Daten-URIs den MIME-Typ application/octet-stream.

    Es gilt dieselbe Obergrenze von 40.000 Flächen wie für input_task_id: Zu große Meshes werden mit einem 400 abgelehnt — führen Sie zuerst Remesh aus.

Rückgabe

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

Fehlermodi

  • Name
    400 - Bad Request
    Description

    Die Anfrage war unzulässig. Häufige Ursachen:

    • Fehlender Parameter: Entweder input_task_id oder model_url muss angegeben werden.
    • Ungültige Eingabeaufgabe: Die input_task_id muss auf eine erfolgreiche Aufgabe mit einem GLB-Ergebnis verweisen.
    • Flächenanzahl überschritten: Das Quellmesh hat mehr Flächen als die UV-Unwrap-Obergrenze. Führen Sie zuerst Remesh aus.
    • Ungültiges Modellformat: Die model_url verweist auf eine Datei mit einer nicht unterstützten Erweiterung.
    • Nicht erreichbare URL: Die model_url konnte nicht heruntergeladen werden.
  • Name
    401 - Unauthorized
    Description

    Authentifizierung fehlgeschlagen. Bitte überprüfen Sie Ihren API key.

  • Name
    402 - Payment Required
    Description

    Nicht genügend Credits, um diese Aufgabe auszuführen. UV Unwrap kostet 5 Credits pro Aufruf.

  • Name
    404 - Not Found
    Description

    Die Funktion ist für Ihr Konto nicht aktiviert. UV Unwrap wird während des Rollouts durch ein Statsig-Flag gesteuert — wenden Sie sich an den Meshy-Support, wenn Sie Zugriff benötigen.

  • Name
    429 - Too Many Requests
    Description

    Sie haben Ihr Ratenlimit ü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

Eine UV-Unwrap-Aufgabe abrufen

Dieser endpoint ruft den aktuellen Status einer UV-Unwrap-Aufgabe anhand der ID ab.

Rückgabe

Gibt ein UV-Unwrap-Aufgabenobjekt 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}"

Siehe das Beispiel-Aufgabenobjekt unten.

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

UV-Unwrap-Aufgabe löschen

Eine UV-Unwrap-Aufgabe dauerhaft löschen. Die Aufgabe und ihre Ausgaben werden unzugänglich.

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-Unwrap-Aufgaben auflisten

Gibt eine paginierte Liste der UV-Unwrap-Aufgaben des Aufrufers zurück, neueste zuerst. 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

UV-Unwrap-Aufgabe streamen

Abonniere den Aufgabenfortschritt als Server-Sent Events. Jedes message-Event enthält ein UV-Unwrap-Aufgabenobjekt; der Stream wird geschlossen, sobald die Aufgabe SUCCEEDED, FAILED oder CANCELED erreicht.

Verwende dies anstelle des Pollings von GET /openapi/v1/uv-unwrap/:id, um eine geringere Latenz beim Abschluss zu erzielen.

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-Unwrap-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

    Vorsignierte Download-URLs für das generierte UV-White-Modell. UV Unwrap gibt immer einen einzelnen glb-Eintrag zurück — die Ausgabe behält die Eingabegeometrie bei, ersetzt sie durch neue UV-Koordinaten und verwendet ein standardmäßiges graues Material anstelle jeglicher Textur.

  • Name
    thumbnail_url
    Type
    string
    Description

    Vorsignierte URL zu einer PNG-Vorschau des UV-White-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 Aufgabe in der Warteschlange stehen. Vorhanden, solange der Status PENDING ist.

  • Name
    created_at
    Type
    timestamp
    Description

    Zeitstempel der Aufgabenerstellung, in Millisekunden.

  • Name
    started_at
    Type
    timestamp
    Description

    Zeitstempel, zu dem die Verarbeitung begonnen hat, in Millisekunden. 0 bis zum Start.

  • Name
    finished_at
    Type
    timestamp
    Description

    Zeitstempel des Abschlusses, in Millisekunden. 0 bis zum Abschluss.

  • 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 Errors für die vollständige task_error-Objektreferenz.

  • Name
    consumed_credits
    Type
    integer
    Description

    Von dieser Aufgabe verbrauchte Credits. Gibt 0 für FAILED-Aufgaben zurück (Credits werden bei Fehlschlag erstattet). UV Unwrap berechnet bei Erfolg 5 Credits.

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
}