Creative Lab Collapsible Fidget API

Verwandeln Sie ein Foto in einem einzigen Task in ein zusammenklappbares Fidget-Spielzeug, das druckfertig ist. Die Silhouette des Motivs wird zu verschachtelten, konzentrischen Ringen, die sich flach zusammenfalten und wieder ausziehen lassen. Das Spielzeug wird in einem Stück gedruckt – ganz ohne Montage.

POST /openapi/creative-lab/fidget-collapsible/v1

Im Gegensatz zu den anderen Creative Lab-Endpoints gibt es hier keine separaten Phasen für Prototyp und Build. Es gibt keine Kandidatenbilder, zwischen denen Sie wählen müssen, daher verwandelt ein einziger Task das Foto in ein 3D-Modell.

Die Anfrage enthält ebenfalls keine Geometrie-Einstellungen. In der Web-App können Sie Größe, Schichtanzahl, Spaltbreite, Wandstärke, Extrusionstiefe und Wölbung festlegen. Jeder API-Task verwendet dafür dieselben Standardwerte.

POST/openapi/creative-lab/fidget-collapsible/v1

Erstelle eine Collapsible-Fidget-Aufgabe

Erzeugt aus einem Foto ein kollabierbares Fidget-Modell. Die Felder der Aufgabe sind unter Das Collapsible-Fidget-Aufgabenobjekt beschrieben.

Jede Aufgabe kostet 6 Credits und erfordert einen kostenpflichtigen Plan.

Request

POST

/openapi/creative-lab/fidget-collapsible/v1

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1 \
  -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": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Parameter

Name
image_url
Type
string
Erforderlich
Description
Das Foto, das in ein Collapsible-Fidget umgewandelt werden soll, als öffentlich zugängliche URL oder als Data URI (data:image/jpeg;base64,<Ihre base64-kodierten Bilddaten>).
Das Bild muss eine JPG-, JPEG-, PNG- oder WebP-Datei mit höchstens 20 MB sein.
Die Silhouette des Motivs wird zu den Ringen, daher funktioniert ein Motiv mit einer klaren, geschlossenen Umrisslinie am besten. Ein unruhiger Hintergrund, mehrere separate Motive oder sehr dünne Formen können zu wenig Fläche für die verschachtelten Wände übrig lassen. In diesem Fall schlägt die Aufgabe fehl.
Name
name
Type
string
Description
Ein Name für die Aufgabe, bis zu 100 Zeichen. Er wird im name-Feld der Aufgabe zurückgegeben, und Meshy graviert ihn nicht in das Modell. Ein längerer Name führt zu 400.

Rückgabewerte

Das Feld result enthält die ID der neuen Aufgabe. Rufen Sie die Aufgabe ab oder streamen Sie sie, bis status den Wert SUCCEEDED hat. Laden Sie dann die druckbare STL-Datei aus model_urls.stl herunter. Um das Modell zunächst in der Vorschau zu betrachten, laden Sie die GLB-Datei aus model_urls.glb herunter, sobald diese vorhanden ist.

Fehlerarten

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, größer als 20 MB oder überschreitet die maximale Pixelanzahl.
- Meshy kann das Bild nicht herunterladen, zum Beispiel weil die URL 404 zurückgibt oder eine Zeitüberschreitung 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. Überprüfen Sie den Authorization-Header.
Name
402 - Payment Required
Description
Einer der folgenden Punkte 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
403 - Forbidden
Description
Ihr Team hat IP Filtering aktiviert, und Meshy hat das Bild wegen geistigen Eigentums Dritter markiert. Senden Sie ein Bild, zu dessen Nutzung Sie berechtigt sind.
Name
429 - Too Many Requests
Description
Eines der folgenden 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 befinden sich in der Warteschlange oder werden gerade 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.
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 die Aufgabe nicht und erstattet alle dafür berechneten Credits zurück. Senden Sie die Anfrage erneut.

GET/openapi/creative-lab/fidget-collapsible/v1/:id

Einen Collapsible-Fidget-Task abrufen

Gibt einen Collapsible-Fidget-Task zurück. Es werden nur Tasks zurückgegeben, die mit diesem Endpunkt erstellt wurden. Ein Task von einem anderen Creative-Lab-Endpunkt oder einer, der in der Web-App erstellt wurde, gibt 404 zurück.

Für die Felder siehe Das Collapsible-Fidget-Task-Objekt.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

Parameter

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

Rückgabewerte

Das Collapsible-Fidget-Task-Objekt.

Fehlerfälle

Name
400 - Bad Request
Description
id ist keine gültige Task-ID. Senden Sie die result-ID aus der Antwort der Erstellung.
Name
403 - Forbidden
Description
Ihr Team hat die IP-Filterung aktiviert, und Meshy hat das Bild des Tasks wegen geistigen Eigentums Dritter markiert. Teams im Enterprise-Plan erhalten diesen Fehler nicht. Erstellen Sie einen Task mit einem Bild, an dem Sie die Nutzungsrechte besitzen.
Name
404 - Not Found
Description
Es gehört kein Collapsible-Fidget-Task mit dieser ID zu Ihrem Konto, oder der Task wurde nicht mit diesem Endpunkt erstellt. Überprüfen Sie die ID.
Name
500 - Internal Server Error
Description
Meshy konnte die Prüfung auf geistiges Eigentum nicht durchführen. Versuchen Sie die Anfrage erneut.

DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Einen Collapsible-Fidget-Task löschen

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

Request

DELETE

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -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ückgabe

204 No Content mit leerem Body.

Fehlerfälle

Name
400 - Bad Request
Description
Einer der folgenden Fälle trifft zu:
- id ist keine gültige Task-ID. Senden Sie die result-ID aus der Antwort der Erstellung.
- 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 Collapsible-Fidget-Task mit dieser ID zu Ihrem Konto, oder der Task wurde nicht mit diesem Endpunkt erstellt. Überprüfen Sie die ID.

GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

Stream einer Collapsible-Fidget-Aufgabe

Streamt die Updates einer Collapsible-Fidget-Aufgabe als Server-Sent Events (SSE). Wenn die Aufgabe nicht existiert oder nicht über diesen Endpunkt erstellt wurde, sendet der Stream ein error-Event mit status_code: 404 und schließt sich.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (task not found, or not created through this endpoint)
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": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

Parameter

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

Rückgabe

Ein Stream von Collapsible-Fidget-Aufgabenobjekten. Jedes Event enthält das vollständige Aufgabenobjekt, so wie es Abrufen einer Collapsible-Fidget-Aufgabe zurückgibt. Solange die Aufgabe PENDING oder IN_PROGRESS ist, sind ihre Ausgabefelder noch leer (null, [] oder {}), und finished_at ist null.

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

GET/openapi/creative-lab/fidget-collapsible/v1

Auflistung der Collapsible-Fidget-Aufgaben

Gibt Ihre Collapsible-Fidget-Aufgaben seitenweise zurück. Es werden nur Aufgaben einbezogen, die mit diesem Endpunkt erstellt wurden.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-fidget-collapsible",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123512000,
    "expires_at": 1729382712000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

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 Collapsible-Fidget-Aufgabenobjekten.

Das Collapsible-Fidget-Task-Objekt

Ein Collapsible-Fidget-Task verwandelt ein Foto in ein druckfertiges, zusammenklappbares Fidget-Modell. Es handelt sich um einen einstufigen Task, sodass es keinen Prototyp-Task gibt, an den er anknüpft. Die Antwort enthält nicht die Silhouette, die Meshy auf dem Weg dorthin erstellt.

Eigenschaften

Example Collapsible Fidget Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?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-fidget-collapsible.
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: endgültig, mit Ergebnis
- FAILED: endgültig, mit dem Grund in task_error
- CANCELED: endgültig, ohne Ergebnis
Name
progress
Type
integer
Description
Prozentsatz der erledigten Arbeit, von 0 bis 100. Der Wert ist 0, bis der Task beginnt, und 100, wenn er erfolgreich ist.
Name
created_at
Type
timestamp
Description
Zeitpunkt, an dem der Task erstellt wurde, in Unix-Millisekunden.
Name
started_at
Type
timestamp
Description
Zeitpunkt, an dem ein Worker den Task gestartet hat, in Unix-Millisekunden. Bis dahin null.
Name
finished_at
Type
timestamp
Description
Zeitpunkt, an dem der Task einen endgültigen Status erreicht hat, in Unix-Millisekunden. Bis dahin null.
Name
expires_at
Type
timestamp
Description
Zeitpunkt, an dem das Ergebnis des Tasks abläuft, in Unix-Millisekunden. Das ist 3 Tage nach finished_at, oder 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 beginnt. 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 den Wert FAILED hat. Siehe Fehler.
Name
consumed_credits
Type
integer
Description
Anzahl der für den Task berechneten Credits, nach einer eventuellen 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 das 3D-Modell, leer, bis der Task erfolgreich ist. Ein erfolgreicher Task hat immer stl und nur dann glb, wenn Meshy die Vorschau gerendert hat.
- Name
  stl
  Type
  string
  Description
  Download-URL für die STL-Datei, die zum Drucken verwendet wird. Sie können sie direkt in einem Slicer öffnen.
- Name
  glb
  Type
  string
  Description
  Download-URL für eine GLB-Datei, um das Modell in einem 3D-Viewer zu betrachten. Ihre Farben dienen nur der Vorschau. Die STL-Datei hat keine Farbe, daher erhält der gedruckte Fidget seine Farbe vom Filament.
  Wenn Meshy die Vorschau nicht rendern kann, enthält model_urls keinen glb-Schlüssel. Prüfen Sie daher, ob der Schlüssel vorhanden ist, bevor Sie ihn auslesen. Ein SUCCEEDED-Task hat immer stl.