Relief API

Verwandeln Sie ein Foto in ein Basrelief-3D-Modell und eine 16-Bit-Tiefenkarte, für 3D-Druck, Lasergravur und CNC-Fräsen.

POST/openapi/v1/relief

Erstellen einer Relief-Aufgabe

Erstellt eine Relief-Aufgabe. Die Aufgabe verwandelt ein Foto in ein Flachrelief-Modell. Bei Erfolg erzeugt die Aufgabe das Modell als GLB-Datei und STL-Datei, eine 16-Bit-Graustufen-Tiefenkarte und ein Vorschaubild. Um nur die Tiefenkarte zu erhalten, setzen Sie should_generate_model auf false.

Die Aufgabe läuft im Hintergrund.

Eine Relief-Aufgabe kann nicht als Eingabe für einen anderen Endpunkt dienen, etwa Remesh, Convert oder Auto Split. Solche Anfragen liefern 403.

Request

POST

/openapi/v1/relief

# Simple request: a low relief, 60 mm on its longer side
curl https://api.meshy.ai/openapi/v1/relief \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

# Advanced request: a deep 120 mm relief with a thicker base, curved from side to side
curl https://api.meshy.ai/openapi/v1/relief \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "variant": "high",
    "size_mm": 120,
    "carving_depth_mm": 10,
    "base_thickness_mm": 3,
    "bend_mode": "convex",
    "bend_angle": 90
  }'

Response

{
  "result": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20"
}

Parameter

Name
image_url
Type
string
Erforderlich
Description
Das Foto, das in ein Relief umgewandelt werden soll, als öffentliche URL oder als Data URI (data:image/png;base64,...).
Das Bild muss eine JPG-, JPEG-, PNG- oder WebP-Datei von höchstens 20 MB und mindestens 32 × 32 Pixel sein. Die längere Seite darf höchstens etwa das 16-Fache der kürzeren Seite betragen. Jedes andere Bild liefert 400. Meshy füllt transparente Bereiche vor dem Erstellen des Reliefs mit Schwarz.
Name
variant
Type
string
Standard low
Description
Der Relief-Stil. Er bestimmt die Tiefenkarte und legt den Standardwert von carving_depth_mm fest.
Verfügbare Werte:
- high: tiefere Gravur, für 3D-gedruckte Teile.
- low: flache Gravur, für Lasergravur, CNC-Gravur und dünne Plaketten.
Das Senden von null oder "" entspricht dem Weglassen des Parameters. Jeder andere Wert liefert 400.
Name
should_generate_model
Type
boolean
Standard true
Description
Ob das Relief-Modell erstellt werden soll. Setzen Sie den Wert auf false für eine Aufgabe, die nur die Tiefenkarte erzeugt, ohne Modell und ohne Vorschaubild. Meshy prüft weiterhin die Größen-, Gravur-, Basis-, Biege- und Auflösungsparameter, verwendet sie jedoch nicht. Dies ändert nicht die Höhe der Credit-Kosten.

Name
size_mm
Type
number
Standard 60
Description
Die Länge der längeren Seite des Fotos auf dem Modell, flach gemessen vor jeder Biegung, von 20 bis 250 Millimeter. Mit remove_base kann das Modell kleiner ausfallen.
Name
carving_mode
Type
string
Standard emboss
Description
Ob das Motiv aus der Platte hervortritt oder in sie hineingeschnitten wird.
Verfügbare Werte:
- emboss: die näheren Teile des Fotos treten hervor.
- engrave: die Tiefe wird umgekehrt, sodass die näheren Teile eingeschnitten werden.
Die Tiefenkarte ist in beiden Modi gleich.
Name
carving_depth_mm
Type
number
Standard 6 (high), 3 (low)
Description
Wie tief das Relief gefräst wird, von 0 bis 60 Millimeter. Wenn remove_base auf true gesetzt ist, ergibt 0 ein leeres Modell. Die Aufgabe ist dennoch erfolgreich und kostet 20 Credits, und ihre GLB- und STL-Dateien enthalten keine Geometrie.

Name
remove_base
Type
boolean
Standard false
Description
Ob der Hintergrund entfernt und keine Grundplatte erstellt werden soll. Wenn der Wert true ist, legt removal_threshold fest, was als Hintergrund gilt. Meshy prüft removal_threshold in jedem Fall.

Gilt nur wenn remove_base = true

Name
removal_threshold
Type
number
Standard 0.01
Description
Die Tiefe, unterhalb derer Meshy den Hintergrund entfernt, von 0.01 bis 1, wobei die Tiefenkarte von 0 bis 1 reicht. Ein hoher Wert kann das gesamte Relief entfernen und ein leeres Modell hinterlassen, das trotzdem erfolgreich erstellt und berechnet wird.

Name
base_thickness_mm
Type
number
Standard 1, or 0 with remove_base
Description
Die Dicke der Grundplatte, von 0.1 bis 10 Millimeter. Wenn remove_base auf true gesetzt ist, lassen Sie den Parameter weg oder senden Sie 0.

Name
bend_mode
Type
string
Standard off
Description
Ob und in welche Richtung das Relief gebogen werden soll. Wenn der Wert nicht off ist, bestimmen bend_axis und bend_angle die Biegung. Meshy prüft sie in jedem Fall.
Verfügbare Werte:
- off: ein flaches Relief.
- convex: die Vorderseite wölbt sich nach außen.
- concave: die Vorderseite krümmt sich nach innen.

Gilt nur wenn bend_mode = convex or concave

Name
bend_axis
Type
string
Standard xz
Description
Welche Kanten sich bei der Biegung krümmen.
Verfügbare Werte:
- xz: die linke und die rechte Kante.
- yz: die obere und die untere Kante.
Name
bend_angle
Type
number
Standard 60
Description
Der Bogen, den die Biegung überspannt, von 0 bis 360 Grad. Unter 1 bleibt das Relief flach.

Name
mesh_resolution
Type
integer
Standard 1024
Description
Die Anzahl der Netzpunkte entlang der längeren Seite des Fotos, von 512 bis 2048. Ein höherer Wert erhält feinere Details und erzeugt größere Dateien. Beim Standardwert 1024 ist die GLB-Datei etwa 40 bis 50 MB und die STL-Datei etwa 80 bis 105 MB groß. Ein quadratisches Foto ergibt die größeren Werte. Bei 2048 sind es etwa 150 MB bzw. 300 MB. Eine Biegung vergrößert die Dateien weiter: Die STL-Datei kann bei 2048 bis zu etwa 800 MB erreichen.

Rückgabewerte

202 Accepted, mit der ID der neuen Relief-Aufgabe in result.

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: image_url wurde nicht gesendet.
- Ungültiger Parameter: Ein Parameter hat den falschen Typ, liegt außerhalb seines Bereichs oder ist keiner der verfügbaren Werte. Zum Beispiel ist variant nicht high oder low, oder mesh_resolution ist keine Ganzzahl von 512 bis 2048.
- Basisdicke: base_thickness_mm ist nicht 0, obwohl remove_base auf true gesetzt ist, oder liegt unter 0.1, ohne dass remove_base gesetzt ist.
- Nicht erreichbare URL: Meshy kann das Bild unter image_url nicht herunterladen, zum Beispiel weil die URL 404 liefert oder ein Timeout auftritt.
- Ungültiges Bild: Das Bild ist keine JPG-, JPEG-, PNG- oder WebP-Datei, ist größer als 20 MB, kleiner als 32 × 32 Pixel, hat zu viele Pixel oder kann nicht gelesen werden.
- Extremes Seitenverhältnis: Die längere Seite des Bildes ist mehr als etwa das 16-Fache der kürzeren Seite.
Korrigieren Sie die Anfrage und senden Sie sie erneut. Meshy berechnet dafür keine Kosten. 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:
- Unzureichende Credits: Das Konto verfügt nicht über genügend Credits für diese Aufgabe, oder das Konto hat ein Credit-Limit erreicht. Prüfen Sie Ihr Credit-Guthaben und versuchen Sie es dann erneut.
- Kostenloser Plan: Das Erstellen einer Aufgabe erfordert einen kostenpflichtigen Plan. Aktualisieren Sie Ihren Plan in Ihren Abonnement-Einstellungen und versuchen Sie es dann erneut.
Name
403 - Forbidden
Description
Die Inhaltsmoderation hat das Bild blockiert. Meshy berechnet für diese Anfrage keine Kosten. Senden Sie ein anderes Bild.
Name
429 - Too Many Requests
Description
Eines dieser Limits wurde erreicht:
- Sie haben zu viele Anfragen gesendet. Warten Sie und versuchen Sie es dann erneut. Siehe Ratenbegrenzungen.
- Zu viele Ihrer Aufgaben sind in der Warteschlange oder laufen bereits. Warten Sie, bis einige abgeschlossen sind, und versuchen Sie es dann erneut.
- Bei einem unbegrenzten Plan ohne verbleibende Credits haben Sie die Anzahl der Aufgaben erreicht, die ohne Credits laufen können. Warten Sie, bis eine Aufgabe abgeschlossen ist, oder fügen Sie Credits hinzu.

Wenn eine Sicherheitsprüfung das Bild während der Ausführung der Aufgabe ablehnt, schlägt die Aufgabe fehl, wobei task_error.type auf invalid_input und task_error.code auf provider_content_refused gesetzt wird. Meshy erstattet die Credits der Aufgabe zurück. Senden Sie ein anderes Bild. Siehe Fehler.

GET/openapi/v1/relief/:id

Einen Relief-Task abrufen

Gibt einen Relief-Task anhand seiner ID zurück.

Request

GET

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20

curl https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

Parameter

Name
id
Type
path
Description
Die Task-ID aus der Antwort der Erstellung.

Rückgabewerte

Das Relief-Task-Objekt.

DELETE/openapi/v1/relief/:id

Eine Relief-Aufgabe löschen

Löscht eine Relief-Aufgabe dauerhaft, einschließlich ihres Modells, der Tiefenkarte und der Daten. Ein Löschvorgang kann nicht rückgängig gemacht werden.

Request

DELETE

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

Pfadparameter

Name
id
Type
path
Description
Die ID der zu löschenden Aufgabe.

Aufgabenstatus

Das Löschen einer PENDING-Aufgabe erstattet die beim Erstellen verwendeten Credits zurück.

Eine IN_PROGRESS-Aufgabe kann nicht gelöscht werden. Die Anfrage gibt 409 Conflict zurück, und die Aufgabe läuft weiter. Meshy erstattet keine Aufgabe, die bereits gestartet wurde, sodass das Löschen Sie sowohl die Credits als auch das Ergebnis kosten würde. Warten Sie, bis sie SUCCEEDED oder FAILED erreicht, und löschen Sie sie dann.

Das Löschen einer SUCCEEDED-Aufgabe erstattet ihre Credits nicht zurück. Eine FAILED-Aufgabe wurde bereits bei ihrem Fehlschlagen erstattet.

Rückgabewerte

200 OK, wenn die Aufgabe gelöscht wurde, oder 409 Conflict, wenn die Aufgabe IN_PROGRESS ist.

GET/openapi/v1/relief

Relief-Aufgaben auflisten

Gibt eine Liste Ihrer Relief-Aufgaben zurück.

Request

GET

/openapi/v1/relief

curl https://api.meshy.ai/openapi/v1/relief?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
    "type": "relief",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
    },
    "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000060000,
    "expires_at": 1700259260000,
    "task_error": null,
    "consumed_credits": 20
  }
]

Parameter

Name
page_num
Type
integer
Description
Die zurückzugebende Seitenzahl. Beginnt bei und ist standardmäßig 1.
Name
page_size
Type
integer
Description
Die Anzahl der Aufgaben pro Seite, bis zu 100. Standardmäßig 10. Meshy behandelt einen Wert von 101 bis 255 als 100, und ein größerer Wert gibt 400 zurück.
Name
sort_by
Type
string
Description
Die Sortierreihenfolge.
Verfügbare Werte:
- +created_at: älteste zuerst
- -created_at: neueste zuerst

Rückgabewerte

Eine paginierte Liste von Relief-Aufgabenobjekten.

GET/openapi/v1/relief/:id/stream

Eine Relief-Aufgabe streamen

Streamt die Updates einer Relief-Aufgabe als Server-Sent Events (SSE).

Request

GET

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/stream

curl -N https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress (other task fields omitted here for brevity;
// each frame is the full task object).
event: message
data: {
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

Parameter

Name
id
Type
path
Description
Die Aufgaben-ID aus der Erstellungsantwort.

Rückgabe

Ein Stream von Relief-Aufgabenobjekten als Server-Sent Events.

Jedes message-Event enthält das vollständige Aufgabenobjekt, dasselbe, das Eine Relief-Aufgabe abrufen zurückgibt. Solange die Aufgabe PENDING oder IN_PROGRESS ist, sind die Felder, die sich zwischen den Events ändern, progress, status, started_at und preceding_tasks (nur vorhanden, solange Aufgaben vor dieser in der Warteschlange stehen). model_urls, depth_map_url und thumbnail_url erhalten ihre Werte, wenn die Aufgabe SUCCEEDED erreicht. Bei einer Aufgabe, die nur eine Tiefenkarte erzeugt, bleibt model_urls {} und thumbnail_url leer.

Ein error-Event enthält nur status_code und message. Prüfen Sie daher den Event-Namen, bevor Sie status auslesen.

Das Relief-Task-Objekt

Ein Relief-Task-Objekt beschreibt ein aus einem Foto erstelltes Relief. model_urls, depth_map_url und thumbnail_url sind immer vorhanden und bleiben leer, bis der Task erfolgreich abgeschlossen ist.

The Relief Task Object

{
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

Depth map only

{
  "id": "0199c3d2-6b8f-7c25-8f3a-4d9e2b7c5a31",
  "type": "relief",
  "model_urls": {},
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-6b8f-7c25-8f3a-4d9e2b7c5a31/output/depth.png?Expires=***",
  "thumbnail_url": "",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1700259230000,
  "task_error": null,
  "consumed_credits": 20
}

Name
id
Type
string
Description
Die Task-ID. Behandeln Sie sie als undurchsichtige Zeichenkette und verlassen Sie sich nicht auf ihr Format.
Name
type
Type
string
Description
Der Task-Typ, immer relief.
Name
model_urls
Type
object
Description
Download-URLs für das Relief-Modell. Die Dateien können groß sein; mesh_resolution listet typische Größen auf.
- Name
  glb
  Type
  string
  Description
  Die GLB-Datei, ohne Textur. Ihre Einheiten sind Meter. Fehlt bei einem reinen Tiefenkarten-Task.
- Name
  stl
  Type
  string
  Description
  Dasselbe Modell als binäre STL-Datei. Ihre Einheiten sind Millimeter, sodass sie in der tatsächlichen Größe des Reliefs geöffnet wird, mit Z nach oben. Fehlt bei einem reinen Tiefenkarten-Task.
Name
depth_map_url
Type
string
Description
Download-URL für die 16-Bit-Graustufen-Tiefenkarte, aus der das Relief erstellt wird. Hellere Pixel sind höher. Die Werte sind relative Höhen, keine Millimeter. Laser-Gravur- und CNC-Software können sie als Höhenkarte verwenden. Die Datei ist etwa 1 bis 2 MB groß. Leer, falls keine vorhanden ist.
Name
thumbnail_url
Type
string
Description
Download-URL für ein Vorschaubild des Relief-Modells. Leer, falls keines gerendert wurde, auch bei einem reinen Tiefenkarten-Task.
Name
progress
Type
integer
Description
Wie viel des Tasks erledigt ist, in Prozent. Der Wert ist 0, bis der Task startet, und 100, wenn er erfolgreich abgeschlossen ist.
Name
status
Type
string
Description
Der Task-Status, einer von PENDING, IN_PROGRESS, SUCCEEDED oder FAILED.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der Tasks, die in der Warteschlange vor diesem liegen. Das Feld wird weggelassen, wenn der Wert 0 ist, sodass es nur erscheint, solange Tasks vor diesem liegen.
Name
created_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task erstellt wurde, 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 abgeschlossen wurde, in Unix-Millisekunden. Der Wert ist 0, bis der Task abgeschlossen ist.
Name
expires_at
Type
timestamp
Description
Zeitpunkt, zu dem das Ergebnis des Tasks abläuft, in Unix-Millisekunden. Der Wert ist 0, bis der Task abgeschlossen ist.
Name
task_error
Type
object
Description
Die Fehlerdetails, wenn der Task fehlschlägt. Siehe Fehler.
Name
consumed_credits
Type
integer
Description
Die Anzahl der vom Task verbrauchten Credits: 20, oder 0 bei einem FAILED-Task, die Meshy erstattet.