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

Erstellen einer UV-Entfaltungsaufgabe

Dieser Endpunkt erstellt eine neue UV-Entfaltungsaufgabe.

Parameter

Genau einer von input_task_id oder model_url ist erforderlich. Wenn beide angegeben sind, 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 UV-entfalten möchten (zum Beispiel ein Bild zu 3D, Text zu 3D oder Neuvernetzungsergebnis). Die Quellaufgabe muss den Status SUCCEEDED haben und eine GLB-Datei erzeugt haben.

    Wenn das Quellnetz die Obergrenze von 40.000 Flächen überschreitet, wird die Anfrage mit einem 400 abgelehnt und Sie sollten zuerst 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 Data URI bereit. Nur .glb wird unterstützt — die API liest glTF-Binärdaten und analysiert keine anderen Formate. Um ein Modell in einem anderen Format (.fbx, .obj, .stl, .gltf) UV-zu-entfalten, konvertieren Sie es zuerst in .glb über die Convert API und übergeben Sie dann die resultierende Aufgaben-ID als input_task_id oder deren GLB-Ausgabe-URL hier.

    Für Data URIs verwenden Sie den MIME-Typ application/octet-stream.

    Die gleiche Obergrenze von 40.000 Flächen gilt wie für input_task_id: übergroße Netze werden mit einem 400 abgelehnt — führen Sie zuerst eine Neuvernetzung durch.

Rückgaben

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

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: Die 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 UV-Entfaltungsgrenze. Führen Sie zuerst eine Neuvernetzung durch.
    • 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-Schlüssel.

  • Name
    402 - Payment Required
    Description

    Unzureichende Credits, um diese Aufgabe auszuführen. UV-Entfaltung kostet 5 Credits pro Aufruf.

  • Name
    404 - Not Found
    Description

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

  • Name
    429 - Too Many Requests
    Description

    Sie haben Ihre Ratenbegrenzung überschritten.

Anfrage

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

Antwort

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