Creative Lab — Collapsible Fidget API

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

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

Anders als bei den übrigen Creative-Lab-Endpoints gibt es hier kein Prototyp-/Build-Stage-Paar — es gibt keine Zwischenkandidaten, zwischen denen man wählen könnte, sodass ein einzelner Task das Bild bis zum fertigen 3D-Modell führt. Auch die Geometrie-Steuerelemente, die die Web-App bereitstellt (Größe, Anzahl der Ebenen, Spaltbreite, Wandstärke, Extrusionstiefe, Wölbung), sind nicht Teil der Anfrage: Jeder Task wird mit denselben serverseitigen Standardwerten erstellt.

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

Erstellen einer Collapsible-Fidget-Aufgabe

Generiert ein zusammenklappbares Fidget-Modell aus einem Ausgangsfoto. Informationen zur 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 einen zusammenklappbaren Fidget verwandeln soll. Derzeit werden die Formate .jpg, .jpeg, .png und .webp unterstützt.

    Es gibt zwei Möglichkeiten, das Bild bereitzustellen:

    • Öffentlich zugängliche URL: Eine URL, die aus dem öffentlichen Internet erreichbar ist.
    • Data URI: Ein Base64-kodierter Data URI des Bildes. Beispiel für einen Data URI: data:image/jpeg;base64,<Ihre Base64-kodierten Bilddaten>.

    Ein Motiv mit einem klaren, geschlossenen Umriss funktioniert am besten – die Silhouette wird zu den Ringen. Unruhige Hintergründe, mehrere separate Motive oder sehr dünne Formen können zu wenig Fläche für die verschachtelten Wände übrig lassen, wodurch die Aufgabe mit einem Aufgabenfehler fehlschlägt.

  • Name
    name
    Type
    string
    Description

    Optionaler Aufgabenname für Anzeigezwecke. Maximal 100 Zeichen. Dies ist nur eine Aufgabenbeschriftung; 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 anschließend das druckbare STL von model_urls.stl herunter (und, falls vorhanden, das GLB von model_urls.glb, um es zunächst in der Vorschau anzuzeigen).

Fehlermodi

  • Name
    400 - Bad Request
    Description

    Die Anfrage war unzulässig. 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ültiger Data URI: Die Base64-Zeichenfolge ist fehlerhaft.
    • Inhalt gekennzeichnet: Das Eingabebild 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 befindet sich Ihr Konto im kostenlosen Plan – die Aufgabenerstellung über diesen Endpunkt erfordert einen kostenpflichtigen Plan – oder Sie haben nicht genügend Credits.

  • Name
    403 - Forbidden
    Description

    Das Eingabebild 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 über die Web-App erstellte Aufgabe liefert 404.

Die Form der Antwort finden Sie unter Das Collapsible-Fidget-Task-Objekt.

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 zum Zeitpunkt der Erstellung verbrauchten Credits zurückerstattet. Aufgaben, die sich bereits IN_PROGRESS befinden, werden ohne Rückerstattung 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 Body 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 Benutzer 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

Streamen einer Collapsible-Fidget-Aufgabe

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

Parameter

  • Name
    id
    Type
    path
    Description

    Eindeutige Kennung für die zu streamende Collapsible-Fidget-Aufgabe.

Rückgabewerte

Gibt einen Stream von Collapsible-Fidget-Aufgabenobjekten als Server-Sent Events zurück. Jeder Frame enthält das vollständige Aufgabenobjekt für die jeweilige Stufe — dieselbe Form, die der Get-Endpunkt zurückgibt — daher sind, solange die Aufgabe PENDING oder IN_PROGRESS ist, die Ausgabefelder einfach noch nicht befüllt (null, [] oder {}) und finished_at ist null.

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 PENDING frame below is abbreviated 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=***"
  }
}
GET/openapi/creative-lab/fidget-collapsible/v1

Liste der zusammenklappbaren Fidget-Aufgaben abrufen

Ruft eine paginierte Liste Ihrer zusammenklappbaren Fidget-Aufgaben ab. Es werden nur Aufgaben 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

    Maximale Seitengröße. Erlaubt sind maximal 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 der zusammenklappbaren Fidget-Aufgabe 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 aus einem Ausgangsfoto ein druckfertiges, zusammenklappbares Fidget-Modell zu erstellen. Es handelt sich um einen einstufigen Task: Es gibt keinen Prototyp, von dem aus verkettet werden könnte, und die Zwischen-Silhouette ist nicht Teil der Antwort.

Eigenschaften

  • Name
    id
    Type
    string
    Description

    Eindeutige Kennung für den Task. Da 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 des Tasks. Der Wert ist creative-lab-fidget-collapsible.

  • Name
    name
    Type
    string
    Description

    Der beim Erstellen des Tasks angegebene Task-Name. Leerer String, wenn kein Name angegeben wurde.

  • Name
    status
    Type
    string
    Description

    Status des Tasks. Mögliche Werte sind PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Fortschritt des Tasks. Wenn der Task noch nicht gestartet wurde, ist diese Eigenschaft 0. Sobald der Task erfolgreich war, wird sie 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Zeitstempel, wann der Task erstellt wurde, 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, wann der Task gestartet wurde, in Millisekunden. Wenn der Task noch nicht gestartet wurde, ist diese Eigenschaft null.

  • Name
    finished_at
    Type
    timestamp
    Description

    Zeitstempel, wann der Task abgeschlossen wurde, in Millisekunden. Wenn der Task noch nicht abgeschlossen ist, ist diese Eigenschaft null.

  • Name
    expires_at
    Type
    timestamp
    Description

    Zeitstempel, wann das Ergebnis des Tasks abläuft, in Millisekunden.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Die Anzahl der vorangehenden Tasks.

    Der Wert dieses Felds ist nur relevant, wenn der Task-Status PENDING ist.

  • Name
    task_error
    Type
    object
    Description

    Fehlerdetails für fehlgeschlagene Tasks. Siehe Fehler für die vollständige Referenz des task_error-Objekts.

  • Name
    consumed_credits
    Type
    integer
    Description

    Die Anzahl der von diesem Task verbrauchten Credits. Vorhanden, wenn der Task-Status PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für FAILED-Tasks zurück (Credits werden bei einem Fehlschlag zurückerstattet).

  • Name
    model_urls
    Type
    object
    Description

    Herunterladbare URLs für das generierte 3D-Modell. Wird befüllt, sobald der Task den Status 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 gedrucktes 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. Lesen Sie ihn daher defensiv aus — stl ist das eigentliche Endergebnis und bei einem SUCCEEDED-Task 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=***"
  }
}