Creative Lab Kühlschrankmagnet API

Verwandeln Sie ein Foto in zwei Schritten in einen 3D-druckbaren Kühlschrankmagnet mit farbigem Relief und flacher Rückseite. Ein Prototyp-Task erzeugt aus dem Foto ein koloriertes Konzeptbild. Ein Build-Task verwandelt dieses Bild in ein 3D-Reliefmodell und verwendet die ID des Prototyp-Tasks als input_task_id.

POST /openapi/creative-lab/fridge-magnet/v1/prototype
POST /openapi/creative-lab/fridge-magnet/v1/build

POST/openapi/creative-lab/fridge-magnet/v1/prototype

Einen Fridge Magnet-Prototyp-Task erstellen

Erzeugt ein farbiges Konzeptbild aus einem Foto. Um das 3D-Modell zu erstellen, übergeben Sie die ID dieses Tasks als input_task_id an den Build-Endpunkt. Die Felder des Tasks finden Sie unter Das Fridge Magnet-Prototyp-Task-Objekt.

Request

POST

/openapi/creative-lab/fridge-magnet/v1/prototype

# Stage 1: generate a colorized fridge magnet concept image
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype \
  -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>"
  }'

Response

{
  "result": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9"
}

Prototyp-Beispiel

Beginnen Sie mit einem Ausgangsfoto und erzeugen Sie dann das Prototypbild, das in der Fridge Magnet-Build-Phase verwendet wird.

Ausgangs-Landschaftsfoto, das als Eingabe für den Creative Lab Fridge Magnet verwendet wird — Prototyp-Eingabe

Aus dem Ausgangsfoto erzeugte Creative Lab Fridge Magnet-Prototypausgabe — Prototyp-Ausgabe

Parameter

Name
image_url
Type
string
Erforderlich
Description
Das Foto, das in ein Kühlschrankmagnet-Konzeptbild umgewandelt werden soll, als öffentliche URL oder als Data URI (data:image/jpeg;base64,<Ihre base64-codierten Bilddaten>).
Das Bild muss eine JPG-, JPEG-, PNG- oder WebP-Datei mit höchstens 20 MB sein.
Name
name
Type
string
Description
Ein Name für den Task, bis zu 100 Zeichen. Er wird im Feld name des Tasks zurückgegeben. Ein längerer Name führt zu 400.
Name
remove_background
Type
boolean
Standard false
Description
Ob der Hintergrund aus dem Prototypbild entfernt werden soll. true liefert ein transparentes RGBA-PNG, das den gesamten Magneten erhält, sodass Sie ihn auf einen beliebigen Hintergrund setzen können. Auch der Build startet dann mit dem Bild ohne Hintergrund. Falls Meshy den Hintergrund nicht entfernen kann, wird das Bild mit Hintergrund zurückgegeben, und der Task gilt weiterhin als erfolgreich.
Die remove_background-Option des Builds ist davon unabhängig.

Rückgabewerte

Das Feld result enthält die ID des neuen Prototyp-Tasks. Rufen Sie den Task ab oder streamen Sie ihn, bis status den Wert SUCCEEDED hat. Übergeben Sie die ID dann als input_task_id an den Build-Endpunkt.

Fehlerfälle

Name
400 - Bad Request
Description
Die Anfrage kann nicht ausgeführt werden. Zum Beispiel:
- image_url fehlt.
- Das Bild ist keine JPG-, JPEG-, PNG- oder WebP-Datei.
- Das Bild ist zu klein, über 20 MB groß oder überschreitet die maximale Pixelanzahl.
- Meshy kann das Bild nicht herunterladen, zum Beispiel weil die URL 404 zurückgibt oder ein Timeout auftritt.
- Die Data URI ist kein gültiges Base64.
- Das Bild wurde als NSFW eingestuft.
Die Fehlermeldung gibt an, welches Problem gefunden wurde. Beheben Sie die Anfrage und senden Sie sie erneut.
Name
401 - Unauthorized
Description
Der API-Schlüssel fehlt oder ist ungültig. Prüfen Sie den Authorization-Header.
Name
402 - Payment Required
Description
Einer der folgenden Fälle trifft zu:
- Das Konto verfügt nicht über genügend Credits.
- Der API-Schlüssel, der Arbeitsbereich oder das Mitglied hat sein Credit-Limit erreicht.
- Das Konto befindet sich im kostenlosen Plan.
Prüfen Sie Ihre Credits und Ihren Plan, und versuchen Sie es erneut.
Name
403 - Forbidden
Description
In Ihrem Team ist IP Filtering aktiviert, und Meshy hat das Bild wegen geistigen Eigentums Dritter markiert. Senden Sie ein Bild, an dem Sie die Nutzungsrechte besitzen.
Name
429 - Too Many Requests
Description
Eines dieser Limits wurde erreicht:
- Sie haben mehr Anfragen gesendet, als Ihre Ratenbegrenzung erlaubt. Warten Sie einige Sekunden und versuchen Sie es erneut. Siehe Ratenbegrenzungen.
- Zu viele Ihrer Tasks befinden sich in der Warteschlange oder laufen gerade. Warten Sie, bis einige abgeschlossen sind, und versuchen Sie es erneut.
- Bei einem unbegrenzten Plan ohne verbleibende Credits haben Sie die Anzahl der Tasks erreicht, die ohne Credits laufen können. Warten Sie, bis ein Task abgeschlossen ist, oder fügen Sie Credits hinzu.
Name
500 - Internal Server Error
Description
Bei Meshy ist ein Serverfehler aufgetreten, zum Beispiel weil die Prüfung auf geistiges Eigentum für das Bild nicht durchgeführt werden konnte. Meshy erstellt den Task nicht und erstattet alle dafür berechneten Credits zurück. Senden Sie die Anfrage erneut.

POST/openapi/creative-lab/fridge-magnet/v1/build

Erstellen einer Kühlschrankmagnet-Build-Aufgabe

Erzeugt den 3D-druckbaren Kühlschrankmagnet aus einer erfolgreich abgeschlossenen Prototyp-Aufgabe. Meshy wandelt das Konzeptbild des Prototyps in ein Tiefenkarten-Relief um und gibt eine Modelldatei im von Ihnen gewählten Format zurück. Die Felder der Aufgabe finden Sie unter Das Kühlschrankmagnet-Build-Aufgabenobjekt.

Request

POST

/openapi/creative-lab/fridge-magnet/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
    "options": {
      "badge_shape": "rounded-rect",
      "size_mm": 60,
      "relief_height_mm": 3.3
    },
    "output": {
      "format": "glb"
    }
  }'

Response

{
  "result": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0"
}

Build example

The build task turns the selected prototype image into a 3D-printable fridge magnet model.

Creative Lab Fridge Magnet build model preview — Build model preview

Parameter

Name
input_task_id
Type
string
Erforderlich
Description
Die ID der zu erstellenden Prototyp-Aufgabe. Es muss sich um eine Aufgabe handeln, die Ihr Konto mit POST /openapi/creative-lab/fridge-magnet/v1/prototype erstellt hat und deren Status SUCCEEDED lautet.
Eine ID, die keiner Ihrer Fridge-Magnet-Prototyp-Aufgaben aus der API entspricht, gibt 404 zurück, einschließlich eines in der Web-App erstellten Prototyps.
Name
name
Type
string
Description
Ein Name für die Aufgabe, bis zu 100 Zeichen. Er wird im Feld name der Aufgabe zurückgegeben. Ein längerer Name gibt 400 zurück.

`options`

Optionale Einstellungen für die Form des Reliefs. Jedes Feld hat einen Standardwert, senden Sie also nur die Felder, die Sie ändern möchten. Ein Wert außerhalb des gültigen Bereichs eines Feldes gibt 400 zurück.

Name
badge_shape
Type
string
Standard rounded-rect
Description
Der Umriss des Magneten, wenn Meshy ihn nicht vom Motiv nachzeichnet. Meshy verwendet ihn, wenn remove_background auf false steht oder wenn der Umriss des Motivs nicht gefunden werden kann.
Verfügbare Werte:
- circle
- rounded-rect
- hexagon
- shield
- star
Name
size_mm
Type
number
Standard 60
Description
Die Kantenlänge des umschließenden Quadrats des Magneten, in Millimetern, bis zu 400. 0 verwendet den Standardwert.
Name
relief_height_mm
Type
number
Standard 3.3
Description
Die maximale Höhe des Reliefs über der Basis, in Millimetern, von 0 bis 20.
Name
relief_offset_mm
Type
number
Standard 0
Description
Wie weit das Relief abgesenkt wird, in Millimetern, von 0 bis 20. Meshy zieht diesen Wert überall von der Höhe des Reliefs ab, bis hinunter zur Basis.
Name
base_thickness_mm
Type
number
Standard 2.0
Description
Die Dicke der flachen Grundplatte hinter dem Relief, in Millimetern, von 0 bis 20. Die Standardbasis von 2 mm gibt dem Magneten genug Substanz, um am Kühlschrank zu haften, sodass sich das Relief nicht zerbrechlich anfühlt.
Name
has_closed_back
Type
boolean
Standard true
Description
Ob die Rückseite des Magneten geschlossen werden soll, die Seite, an die der Magnet geklebt wird. false lässt die Rückseite offen, als Schale.
Name
relief_curve
Type
string
Standard linear
Description
Die Kurve, die Tiefenkartenwerte auf die Relief-Höhe abbildet.
Verfügbare Werte:
- linear
- gamma
- s-curve
Name
curve_param
Type
number
Standard 1.0
Description
Die Stärke der Kurve, bis zu 10. Die Kurven gamma und s-curve verwenden diesen Wert, linear ignoriert ihn. 0 verwendet den Standardwert.
Name
invert_depth
Type
boolean
Standard false
Description
Ob die Tiefenkarte invertiert werden soll, sodass dunklere Bereiche zu einem höheren Relief werden.
Name
smoothing
Type
number
Standard 0.24
Description
Wie stark die Tiefenkarte geglättet werden soll, bevor Meshy das Relief erstellt, von 0 bis 10.
Name
relief_scale
Type
number
Standard 1.0
Description
Wie stark das Relief und seine Textur innerhalb des Umrisses um die Mitte herum gezoomt werden sollen, bis zu 10. Ein Wert über 1 vergrößert das Motiv, ein Wert unter 1 verkleinert es. Die Höhe des Reliefs wird dadurch nicht verändert. 0 verwendet den Standardwert.
Name
depth_threshold
Type
number
Standard 0.1
Description
Der Tiefenkartenwert, unter dem Meshy die Tiefe auf null setzt, von 0 bis 1.
Name
remove_background
Type
boolean
Standard true
Description
Ob der Umriss des Magneten vom Motiv nachgezeichnet werden soll, sodass der Magnet der Form des Motivs folgt. false verwendet stattdessen den Umriss von badge_shape. Meshy verwendet badge_shape auch dann, wenn der Umriss des Motivs nicht gefunden werden kann.
Dies ist unabhängig vom remove_background-Parameter des Prototyps, der festlegt, ob das Prototypbild einen transparenten Hintergrund hat.
Name
export_resolution
Type
integer
Standard 512
Description
Die Netzauflösung des exportierten Modells, von 64 bis 512. Meshy erstellt die Geometrie aus einer 512-Pixel-Tiefenkarte, sodass ein feineres Netz zusätzliche Flächen hinzufügen würde, ohne mehr Detail zu liefern. 0 verwendet den Standardwert.

`output`

Optional. Legt das Dateiformat fest, das der Build zurückgibt.

Name
format
Type
string
Standard glb
Description
Das Dateiformat, das der Build zurückgibt.
Verfügbare Werte:
- glb: eine model.glb-Datei, in model_urls.glb
- obj: eine ZIP-Datei mit model.obj, model.mtl und texture.png, in model_urls.obj
- zip: eine ZIP-Datei mit allen von Meshy erzeugten Dateien, in model_urls.bundle_zip

Rückgabewerte

Das Feld result enthält die ID der neuen Build-Aufgabe. Rufen Sie die Aufgabe ab oder streamen Sie sie, bis status den Wert SUCCEEDED hat. Laden Sie die Datei anschließend über den einzigen Eintrag in model_urls herunter.

Fehlermodi

Name
400 - Bad Request
Description
Die Anfrage kann nicht ausgeführt werden. Zum Beispiel:
- input_task_id fehlt oder ist keine gültige Aufgaben-ID.
- Der Status der Prototyp-Aufgabe ist nicht SUCCEEDED. Wenn sie noch läuft, warten Sie und versuchen Sie es erneut. Wenn sie fehlgeschlagen oder abgebrochen wurde, erstellen Sie eine neue Prototyp-Aufgabe.
- Die Prototyp-Aufgabe war erfolgreich, enthält aber kein Bild. Erstellen Sie eine neue Prototyp-Aufgabe.
- Ein options-Feld liegt außerhalb seines Bereichs oder ist kein verfügbarer Wert.
Die Fehlermeldung gibt an, welches Problem gefunden wurde.
Name
401 - Unauthorized
Description
Der API-Schlüssel fehlt oder ist ungültig. Überprüfen Sie den Authorization-Header.
Name
402 - Payment Required
Description
Einer der folgenden Fälle trifft zu:
- Das Konto verfügt nicht über genügend Credits.
- Der API-Schlüssel, der Arbeitsbereich oder das Mitglied hat sein Credit-Limit erreicht.
- Das Konto nutzt den kostenlosen Plan.
Überprüfen Sie Ihre Credits und Ihren Plan und versuchen Sie es erneut.
Name
404 - Not Found
Description
input_task_id entspricht keiner Fridge-Magnet-Prototyp-Aufgabe, die Ihr Konto mit der API erstellt hat. Ein in der Web-App erstellter Prototyp gibt ebenfalls 404 zurück. Senden Sie die result-ID aus einer Antwort auf die Prototyp-Erstellung.
Name
429 - Too Many Requests
Description
Eines dieser Limits wurde erreicht:
- Sie haben mehr Anfragen gesendet, als Ihre Ratenbegrenzung erlaubt. Warten Sie einige Sekunden und versuchen Sie es erneut. Siehe Ratenbegrenzungen.
- Zu viele Ihrer Aufgaben sind in der Warteschlange oder werden ausgeführt. Warten Sie, bis einige abgeschlossen sind, und versuchen Sie es erneut.
- Bei einem unbegrenzten Plan ohne verbleibende Credits haben Sie die Anzahl der Aufgaben erreicht, die ohne Credits ausgeführt werden können. Warten Sie, bis eine Aufgabe abgeschlossen ist, oder fügen Sie Credits hinzu.

GET/openapi/creative-lab/fridge-magnet/v1/(prototype|build)/:id

Fridge-Magnet-Task abrufen

Gibt einen Prototyp- oder Build-Task zurück. Der Pfad muss zur Stufe des Tasks passen. Ein Build-Task, der über /prototype/:id angefragt wird, gibt 404 zurück, ebenso ein Prototyp-Task, der über /build/:id angefragt wird.

Die Felder finden Sie unter Das Fridge-Magnet-Prototyp-Task-Objekt und Das Fridge-Magnet-Build-Task-Objekt.

Request

GET

/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
  "type": "creative-lab-fridge-magnet-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543210000,
  "started_at": 1729543215000,
  "finished_at": 1729543242000,
  "expires_at": 1729802442000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "type": "creative-lab-fridge-magnet-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543250000,
  "started_at": 1729543258000,
  "finished_at": 1729543285000,
  "expires_at": 1729802485000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
  }
}

Parameter

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

Rückgabewerte

Das Prototyp-Task-Objekt oder das Build-Task-Objekt, passend zur Stufe im Pfad.

Fehlermodi

Name
400 - Bad Request
Description
id ist keine gültige Task-ID. Senden Sie die result-ID aus der Erstellungsantwort.
Name
403 - Forbidden
Description
Ihr Team hat IP-Filterung aktiviert, und Meshy hat das Bild des Prototyp-Tasks wegen geistigen Eigentums Dritter markiert. Build-Tasks und Teams im Enterprise-Plan erhalten diesen Fehler nicht. Erstellen Sie einen Prototyp-Task aus einem Bild, an dem Sie die Nutzungsrechte besitzen.
Name
404 - Not Found
Description
Es gehört kein Fridge-Magnet-Task mit dieser ID zu Ihrem Konto, oder die Stufe des Tasks stimmt nicht mit dem Pfad überein. Überprüfen Sie die ID und verwenden Sie /prototype oder /build, passend zum Task.
Name
500 - Internal Server Error
Description
Meshy konnte die Prüfung auf geistiges Eigentum nicht durchführen. Wiederholen Sie die Anfrage.

DELETE/openapi/creative-lab/fridge-magnet/v1/(prototype|build)/:id

Einen Kühlschrankmagnet-Task löschen

Bricht einen Kühlschrankmagnet-Task ab. Das Abbrechen eines PENDING-Tasks erstattet dessen Credits zurück. Ein IN_PROGRESS-Task wird ohne Rückerstattung abgebrochen, da bereits ein Worker mit der Bearbeitung begonnen hat. Ein Task mit einem endgültigen Status (SUCCEEDED, FAILED oder CANCELED) kann nicht abgebrochen werden.

Der Pfad muss zur Stufe des Tasks passen. Zum Beispiel gibt DELETE auf /prototype/:id mit der ID eines Build-Tasks 404 zurück.

Request

DELETE

/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

Pfadparameter

Name
id
Type
path
Description
Die ID des abzubrechenden Tasks.

Rückgabewerte

204 No Content mit leerem Body.

Fehlerfälle

Name
400 - Bad Request
Description
Einer der folgenden Punkte trifft zu:
- id ist keine gültige Task-ID. Senden Sie die result-ID aus der Erstellungsantwort.
- Der Task hat bereits einen endgültigen Status (SUCCEEDED, FAILED oder CANCELED) und kann daher nicht abgebrochen werden.
Name
404 - Not Found
Description
Es gehört kein Kühlschrankmagnet-Task mit dieser ID zu Ihrem Konto, oder die Stufe des Tasks stimmt nicht mit dem Pfad überein. Überprüfen Sie die ID und verwenden Sie /prototype oder /build, um den Task zuzuordnen.

GET/openapi/creative-lab/fridge-magnet/v1/(prototype|build)/:id/stream

Einen Kühlschrankmagnet-Task streamen

Streamt die Updates eines Kühlschrankmagnet-Tasks als Server-Sent Events (SSE). Der Pfad muss zur Stufe des Tasks passen. Ist dies nicht der Fall, zum Beispiel wenn die ID eines Build-Tasks an /prototype/:id/stream gesendet wird, sendet der Stream ein error-Event mit status_code: 404 und wird geschlossen.

Request

GET

/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The following PENDING frame is shortened to the fields that change.
event: message
data: {
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "type": "creative-lab-fridge-magnet-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543250000,
  "started_at": 1729543258000,
  "finished_at": 1729543285000,
  "expires_at": 1729802485000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
  }
}

Parameter

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

Rückgabe

Ein Stream von prototype- oder build-Task-Objekten. Jedes Event enthält das vollständige Task-Objekt, so wie es Einen Kühlschrankmagnet-Task abrufen zurückgibt. Solange der Task PENDING oder IN_PROGRESS ist, sind seine Ausgabefelder noch leer (null, [] oder {}), und finished_at ist null.

Falls IP-Filterung das Ergebnis des Tasks blockiert, sendet der Stream stattdessen ein error-Event mit dem status_code, den eine Get-Anfrage zurückgeben würde.

GET/openapi/creative-lab/fridge-magnet/v1/(prototype|build)

Liste der Kühlschrankmagnet-Aufgaben abrufen

Gibt Ihre Kühlschrankmagnet-Aufgaben einer Stufe zurück, jeweils eine Seite auf einmal. Der Pfad wählt die Stufe aus. /prototype gibt nur Prototyp-Aufgaben zurück, und /build gibt nur Build-Aufgaben zurück.

Request

GET

/openapi/creative-lab/fridge-magnet/v1/prototype

# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
    "type": "creative-lab-fridge-magnet-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729543210000,
    "started_at": 1729543215000,
    "finished_at": 1729543242000,
    "expires_at": 1729802442000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

Pfadparameter

Name
stage
Type
path
Erforderlich
Description
Die aufzulistende Stufe, prototype oder build.

Abfrageparameter

Name
page_num
Type
integer
Standard 1
Description
Die zurückzugebende Seite, von 1 bis 255. 0 gibt die erste Seite zurück. Ein Wert außerhalb von 0 bis 255 gibt 400 zurück.
Name
page_size
Type
integer
Standard 10
Description
Anzahl der Aufgaben pro Seite, bis zu 100. Ein Wert von 101 bis 255 gibt 100 Aufgaben zurück, und 0 verwendet den Standardwert. Ein Wert außerhalb von 0 bis 255 gibt 400 zurück.
Name
sort_by
Type
string
Standard -created_at
Description
Die Sortierreihenfolge.
Verfügbare Werte:
- -created_at: neueste zuerst
- +created_at: älteste zuerst

Rückgabewerte

Ein Array von Prototyp-Aufgabenobjekten oder Build-Aufgabenobjekten, passend zur Stufe im Pfad.

Das Fridge-Magnet-Prototyp-Task-Objekt

Ein Prototyp-Task erzeugt ein farbiges Konzeptbild aus einem Foto. Um das Bild in ein 3D-Modell umzuwandeln, übergeben Sie die ID des Tasks als input_task_id an den Build-Endpunkt.

Eigenschaften

Example Fridge Magnet Prototype Task Object

{
  "id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
  "type": "creative-lab-fridge-magnet-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543210000,
  "started_at": 1729543215000,
  "finished_at": 1729543242000,
  "expires_at": 1729802442000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Name
id
Type
string
Description
Die Task-ID. Verlassen Sie sich nicht auf ihr Format.
Name
type
Type
string
Description
Der Task-Typ, immer creative-lab-fridge-magnet-prototype.
Name
name
Type
string
Description
Der name, den Sie beim Erstellen des Tasks gesendet haben, oder "", wenn Sie keinen gesendet haben.
Name
status
Type
string
Description
Der Status des Tasks.
Verfügbare Werte:
- PENDING: wartet in der Warteschlange
- IN_PROGRESS: generiert das Ergebnis
- SUCCEEDED: final, mit Ergebnis
- FAILED: final, mit dem Grund in task_error
- CANCELED: final, ohne Ergebnis
Name
progress
Type
integer
Description
Prozentsatz der erledigten Arbeit, von 0 bis 100. Der Wert ist 0, bis der Task startet, und 100, wenn er erfolgreich ist.
Name
created_at
Type
timestamp
Description
Zeitpunkt der Erstellung des Tasks, in Unix-Millisekunden.
Name
started_at
Type
timestamp
Description
Zeitpunkt, zu dem ein Worker den Task gestartet hat, in Unix-Millisekunden. Bis dahin null.
Name
finished_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task einen finalen Status erreicht hat, in Unix-Millisekunden. Bis dahin null.
Name
expires_at
Type
timestamp
Description
Zeitpunkt, zu dem das Ergebnis des Tasks abläuft, in Unix-Millisekunden. Das sind 3 Tage nach finished_at, bzw. 3 Tage nach created_at, solange der Task noch nicht abgeschlossen ist. Bei Enterprise-Konten, die API-Ergebnisse unbegrenzt aufbewahren, liegt der Wert etwa 100 Jahre später. Siehe Aufbewahrung von Assets.
Name
preceding_tasks
Type
integer
Description
Die Position des Tasks in der Warteschlange, solange er PENDING ist. 1 bedeutet, dass er als Nächstes startet. 0, nachdem der Task die Warteschlange verlassen hat, und immer 0 in Listenergebnissen.
Name
task_error
Type
object
Description
Warum der Task fehlgeschlagen ist. null, sofern status nicht FAILED ist. Siehe Fehler.
Name
consumed_credits
Type
integer
Description
Anzahl der für den Task berechneten Credits, nach etwaiger Rückerstattung. Eine Anfrage, die einen Fehler zurückgibt, wird nicht berechnet. Ein fehlgeschlagener Task hat den Wert 0, da Meshy ihn erstattet. Ein Abbruch erstattet einen Task nur, solange er PENDING ist. Wenn Meshy die Belastung nicht auslesen kann, lässt eine get- oder stream-Antwort das Feld weg, und eine Listenanfrage gibt 500 zurück. Wiederholen Sie in diesem Fall die Anfrage.
Name
image_urls
Type
array of strings
Description
Download-URLs für das Konzeptbild. Das Array enthält eine URL, nachdem der Task erfolgreich war, und ist bis dahin leer.

Das Fridge-Magnet-Build-Task-Objekt

Ein Build-Task generiert den 3D-Kühlschrankmagneten aus einem erfolgreichen Prototype-Task. Er liefert eine Modelldatei im von Ihnen angeforderten Format zurück.

Eigenschaften

Example Fridge Magnet Build Task Object

{
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "type": "creative-lab-fridge-magnet-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543250000,
  "started_at": 1729543258000,
  "finished_at": 1729543285000,
  "expires_at": 1729802485000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
  }
}

Name
id
Type
string
Description
Die Task-ID. Verlassen Sie sich nicht auf ihr Format.
Name
type
Type
string
Description
Der Task-Typ, immer creative-lab-fridge-magnet-build.
Name
name
Type
string
Description
Der name, den Sie beim Erstellen des Tasks gesendet haben, oder "", wenn Sie keinen gesendet haben.
Name
status
Type
string
Description
Der Status des Tasks.
Verfügbare Werte:
- PENDING: wartet in der Warteschlange
- IN_PROGRESS: Ergebnis wird generiert
- SUCCEEDED: final, mit Ergebnis
- FAILED: final, mit dem Grund in task_error
- CANCELED: final, ohne Ergebnis
Name
progress
Type
integer
Description
Prozentsatz der erledigten Arbeit, von 0 bis 100. Er ist 0, bis der Task startet, und 100, wenn er erfolgreich ist.
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 ein Worker den Task gestartet hat, in Unix-Millisekunden. Bis dahin null.
Name
finished_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task einen finalen Status erreicht hat, in Unix-Millisekunden. Bis dahin null.
Name
expires_at
Type
timestamp
Description
Zeitpunkt, zu dem das Ergebnis des Tasks abläuft, in Unix-Millisekunden. Das sind 3 Tage nach finished_at, oder, solange der Task noch nicht abgeschlossen ist, 3 Tage nach created_at. Bei Enterprise-Konten, die API-Ergebnisse unbegrenzt aufbewahren, liegt er etwa 100 Jahre später. Siehe Aufbewahrung von Assets.
Name
preceding_tasks
Type
integer
Description
Die Position des Tasks in der Warteschlange, während er PENDING ist. 1 bedeutet, dass er als Nächstes startet. 0, nachdem der Task die Warteschlange verlassen hat, und immer 0 in Listenergebnissen.
Name
task_error
Type
object
Description
Warum der Task fehlgeschlagen ist. null, außer wenn status FAILED ist. Siehe Fehler.
Name
consumed_credits
Type
integer
Description
Anzahl der für den Task berechneten Credits, nach etwaiger Rückerstattung. Eine Anfrage, die einen Fehler zurückgibt, wird nicht berechnet. Ein fehlgeschlagener Task hat den Wert 0, da Meshy ihn erstattet. Ein Abbruch erstattet einen Task nur, solange er PENDING ist. Wenn Meshy die Belastung nicht auslesen kann, lässt eine get- oder stream-Antwort das Feld weg, und eine Listenanfrage gibt 500 zurück. Wiederholen Sie in diesem Fall die Anfrage.
Name
model_urls
Type
object
Description
Download-URLs für die Modelldatei, mit einem Eintrag für das von Ihnen angeforderte output.format. {}, bis der Task erfolgreich ist.
- Name
  glb
  Type
  string
  Description
  Download-URL für die GLB-Datei. Vorhanden, wenn output.format glb ist.
- Name
  obj
  Type
  string
  Description
  Download-URL für eine ZIP-Datei mit model.obj, model.mtl und texture.png. Vorhanden, wenn output.format obj ist.
- Name
  bundle_zip
  Type
  string
  Description
  Download-URL für eine ZIP-Datei mit allen von Meshy generierten Dateien. Vorhanden, wenn output.format zip ist.