Creative Lab — Collapsible Fidget API

Verwandeln Sie ein Ausgangsfoto in ein druckfertiges, zusammenklappbares Fidget-Spielzeug: Die Silhouette des Motivs wird zu einer Reihe verschachtelter konzentrischer Ringe, die sich flach zusammenklappen und wieder auseinanderziehen lassen und die in einem Stück ohne Montage gedruckt werden.

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

Anders als die übrigen Creative-Lab-Endpoints besitzt dieser kein Prototyp-/Build-Stufenpaar — es gibt keine Zwischenkandidaten, zwischen denen gewählt werden muss, sodass eine einzelne Task das Bild direkt bis zum 3D-Modell führt. Auch die Geometrie-Steuerelemente, die die Web-App bereitstellt (Größe, Anzahl der Schichten, Spaltbreite, Wandstärke, Extrusionstiefe, Wölbung), sind nicht Teil der Anfrage: Jede Task wird mit denselben serverseitigen Standardwerten erstellt.

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

Erstellen einer Collapsible-Fidget-Aufgabe

Erzeugt aus einem Ausgangsfoto ein zusammenklappbares Fidget-Modell (Collapsible Fidget). Die Form der Antwort finden Sie unter Das Collapsible-Fidget-Task-Objekt.

Jede Aufgabe kostet 6 Credits und erfordert einen kostenpflichtigen Plan.

Parameter

Name
image_url
Type
string
Erforderlich
Description
Ausgangsfoto, das Meshy in ein Collapsible Fidget verwandeln soll. Wir unterstützen derzeit die Formate .jpg, .jpeg, .png und .webp.
Es gibt zwei Möglichkeiten, das Bild bereitzustellen:
- Öffentlich zugängliche URL: Eine URL, die aus dem öffentlichen Internet erreichbar ist.
- Data URI: Eine base64-codierte Data URI des Bildes. Beispiel für eine Data URI: data:image/jpeg;base64,<Ihre base64-codierten Bilddaten>.
Ein Motiv mit einer klaren, geschlossenen Umrisslinie eignet sich am besten – die Silhouette wird zu den Ringen. Unruhige Hintergründe, mehrere getrennte Motive oder sehr dünne Formen lassen möglicherweise zu wenig Fläche für die verschachtelten Wände übrig, wodurch die Aufgabe mit einem Task-Fehler fehlschlägt.
Name
name
Type
string
Description
Optionaler Aufgabenname zu Anzeigezwecken. Maximal 100 Zeichen. Dies ist nur eine Aufgabenbezeichnung; auf dem Modell wird nichts eingraviert.

Rückgabewerte

Die Eigenschaft result der Antwort enthält die id der neu erstellten Collapsible-Fidget-Aufgabe. Fragen Sie den Get a Task-Endpunkt ab oder abonnieren Sie den Stream, bis die Aufgabe den Status SUCCEEDED erreicht, und laden Sie dann die druckbare STL-Datei über model_urls.stl herunter (und, falls vorhanden, das GLB über model_urls.glb, um es zuerst in der Vorschau anzuzeigen).

Fehlerfälle

Name
400 - Bad Request
Description
Die Anfrage war nicht akzeptabel. Häufige Ursachen:
- Fehlender Parameter: image_url ist erforderlich.
- Ungültiges Bildformat: Die angegebene image_url hat kein unterstütztes Format (.jpg, .jpeg, .png, .webp).
- Bildabmessungen außerhalb des zulässigen Bereichs: Das Bild ist zu klein, überschreitet die maximale Dateigröße oder überschreitet die maximale Pixelanzahl.
- Nicht erreichbare URL: Die image_url konnte nicht heruntergeladen werden (404 oder timeout).
- Ungültige Data URI: Die base64-Zeichenfolge ist fehlerhaft.
- Inhalt gekennzeichnet: Das eingereichte Bild wurde von der NSFW-moderation gekennzeichnet.
Name
401 - Unauthorized
Description
Die Authentifizierung ist fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.
Name
402 - Payment Required
Description
Entweder nutzt Ihr Konto den kostenlosen Plan – die Erstellung von Aufgaben über diesen Endpunkt erfordert einen kostenpflichtigen Plan – oder Sie verfügen über nicht ausreichende Credits.
Name
403 - Forbidden
Description
Das eingereichte Bild wurde wegen einer Verletzung geistigen Eigentums gekennzeichnet.
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten.

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

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

Abrufen einer Collapsible-Fidget-Aufgabe

Ruft eine Collapsible-Fidget-Aufgabe anhand einer gültigen Aufgaben-id ab. Nur Aufgaben, die über diesen Endpunkt erstellt wurden, sind hier adressierbar — eine Aufgabe von einem anderen Creative-Lab-Endpunkt oder eine in der Web-App erstellte Aufgabe liefert 404 zurück.

Siehe Das Collapsible-Fidget-Task-Objekt für die Struktur der Antwort.

Parameter

Name
id
Type
path
Description
Eindeutige Kennung der abzurufenden Collapsible-Fidget-Aufgabe.

Rückgabewerte

Die Antwort enthält 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=***"
  }
}

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

Eine zusammenklappbare Fidget-Aufgabe löschen

Bricht eine zusammenklappbare Fidget-Aufgabe ab. Wenn sich die Aufgabe noch im Status PENDING befindet, werden die bei der Erstellung verbrauchten Credits erstattet. Aufgaben, die sich bereits im Status IN_PROGRESS befinden, werden ohne Erstattung abgebrochen (der Worker verbraucht möglicherweise bereits Ressourcen). Aufgaben, die bereits einen Endzustand erreicht haben (SUCCEEDED, FAILED, CANCELED), können nicht abgebrochen werden.

Pfadparameter

Name
id
Type
path
Description
Eindeutige Kennung der abzubrechenden zusammenklappbaren Fidget-Aufgabe.

Rückgabewerte

Gibt bei Erfolg 204 No Content mit leerem Inhalt zurück.

Fehlerfälle

Name
400 - Bad Request
Description
Die Aufgabe befindet sich bereits in einem Endzustand und kann nicht abgebrochen werden.
Name
404 - Not Found
Description
Die Aufgabe existiert nicht, gehört einem anderen Nutzer oder wurde nicht über diesen Endpunkt erstellt.

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).

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

Einen Collapsible-Fidget-Task streamen

Streamt Echtzeit-Updates für einen Collapsible-Fidget-Task über Server-Sent Events (SSE). Ein Task, der nicht existiert oder nicht über diesen Endpunkt erstellt wurde, sendet ein einzelnes event: error-Payload mit status_code: 404 und schließt den Stream.

Parameter

Name
id
Type
path
Description
Eindeutige Kennung des zu streamenden Collapsible-Fidget-Tasks.

Rückgabewerte

Gibt einen Stream von Collapsible-Fidget-Task-Objekten als Server-Sent Events zurück. Bei PENDING- oder IN_PROGRESS-Tasks enthält der Antwort-Stream nur die notwendigen Felder progress und status.

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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=***"
  }
}

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

Liste der zusammenklappbaren Fidget-Tasks

Ruft eine paginierte Liste Ihrer zusammenklappbaren Fidget-Tasks ab. Es werden nur Tasks berücksichtigt, die über diesen Endpunkt erstellt wurden.

Abfrageparameter

Name
page_num
Type
integer
Standard 1
Description
Seitennummer für die Paginierung.
Name
page_size
Type
integer
Standard 10
Description
Begrenzung der Seitengröße. Maximal zulässig sind 100 Einträge.
Name
sort_by
Type
string
Standard -created_at
Description
Feld, nach dem sortiert werden soll. Verfügbare Werte:
- +created_at: Sortierung nach Erstellungszeit in aufsteigender Reihenfolge.
- -created_at: Sortierung nach Erstellungszeit in absteigender Reihenfolge.

Rückgabewerte

Gibt eine paginierte Liste von dem Objekt des zusammenklappbaren Fidget-Tasks zurück.

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=***"
    }
  }
]

Das Collapsible Fidget Task Objekt

Das Collapsible Fidget Task Objekt ist eine Arbeitseinheit, die Meshy verfolgt, um ein Ausgangsfoto in ein druckbares, zusammenklappbares Fidget-Modell (print-in-place) umzuwandeln. Es handelt sich um eine einstufige Aufgabe: Es gibt keinen Prototyp, von dem verkettet werden könnte, und das Zwischenergebnis-Silhouette ist nicht Teil der Antwort.

Eigenschaften

Name
id
Type
string
Description
Eindeutiger Bezeichner für die Aufgabe. Obwohl wir als Implementierungsdetail eine k-sortierbare UUID für Task-IDs verwenden, sollten Sie keine Annahmen über das Format der ID treffen.
Name
type
Type
string
Description
Typ der Aufgabe. Der Wert ist creative-lab-fidget-collapsible.
Name
name
Type
string
Description
Der Aufgabenname, der bei der Erstellung der Aufgabe angegeben wurde. Leerer String, wenn kein Name angegeben wurde.
Name
status
Type
string
Description
Status der Aufgabe. Mögliche Werte sind PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Fortschritt der Aufgabe. Wenn die Aufgabe noch nicht gestartet wurde, ist dieser Wert 0. Sobald die Aufgabe erfolgreich abgeschlossen wurde, wird dieser Wert 100.
Name
created_at
Type
timestamp
Description
Zeitstempel der Erstellung der Aufgabe, in Millisekunden.
Ein Zeitstempel repräsentiert die Anzahl der Millisekunden, die seit dem 1. Januar 1970 UTC vergangen sind, gemäß dem Standard RFC 3339. Zum Beispiel wird Freitag, der 1. September 2023, 12:00:00 Uhr GMT als 1693569600000 dargestellt. Dies gilt für alle Zeitstempel in der Meshy API.
Name
started_at
Type
timestamp
Description
Zeitstempel des Starts der Aufgabe, in Millisekunden. Wenn die Aufgabe noch nicht gestartet wurde, ist dieser Wert null.
Name
finished_at
Type
timestamp
Description
Zeitstempel des Abschlusses der Aufgabe, in Millisekunden. Wenn die Aufgabe noch nicht abgeschlossen wurde, ist dieser Wert null.
Name
expires_at
Type
timestamp
Description
Zeitstempel, zu dem das Ergebnis der Aufgabe abläuft, in Millisekunden.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der vorangehenden Aufgaben.
Der Wert dieses Feldes ist nur relevant, wenn der Aufgabenstatus PENDING ist.
Name
task_error
Type
object
Description
Fehlerdetails für fehlgeschlagene Aufgaben. Siehe Fehler für die vollständige Referenz zum task_error-Objekt.
Name
consumed_credits
Type
integer
Description
Die Anzahl der von dieser Aufgabe verbrauchten Credits. Vorhanden, wenn der Aufgabenstatus PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für FAILED-Aufgaben zurück (Credits werden bei einem Fehlschlag erstattet).
Name
model_urls
Type
object
Description
Herunterladbare URLs für das generierte 3D-Modell. Wird befüllt, sobald die Aufgabe SUCCEEDED erreicht hat: stl ist immer vorhanden, glb nur, wenn das Vorschau-Rendering erfolgreich war.
- Name
  stl
  Type
  string
  Description
  Herunterladbare URL zur STL-Datei. Dies ist das druckbare Endergebnis — senden Sie es direkt an einen Slicer.
- Name
  glb
  Type
  string
  Description
  Herunterladbare URL zur GLB-Datei, zur Vorschau des Modells in einem 3D-Viewer. Ihre Farben dienen nur der Vorschau: STL enthält keine Farbinformationen, und ein gedruckter Fidget erhält seine Farbe vom Filament. Die GLB-Datei wird nach bestem Bemühen bereitgestellt: Wenn das Vorschau-Rendering nicht verfügbar ist, wird der Schlüssel vollständig aus model_urls weggelassen. Behandeln Sie ihn daher defensiv — stl ist das eigentliche Ergebnis und bei einer SUCCEEDED-Aufgabe immer vorhanden.

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=***"
  }
}