Creative Lab — Fidget Pixel API

Quellfoto, das Meshy pixeln soll. Wir unterstützen derzeit die Formate .jpg, .jpeg, .png und .webp.

Das Format wird durch das Dekodieren der Bilddaten ermittelt, nicht anhand der Dateiendung der URL – eine URL ohne Erweiterung oder eine, die weiterleitet, funktioniert, solange die Bytes zu einem unterstützten Format dekodiert werden. HTTP-Weiterleitungen werden befolgt.

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

Was das Foto zeigt. Wählt den Pixelisierungsstil aus, wählen Sie also bewusst – die beiden Optionen erzeugen sichtbar unterschiedliche Ergebnisse. Verfügbare Werte:

• person — das Motiv ist eine Person (Porträt oder Ganzkörper). Erzeugt ein Pixel-Sprite des Motivs im Chibi-Stil.
• other — alles andere: Haustiere, Objekte, Maskottchen, Logos, Landschaften. Erzeugt ein Pixel-Icon des Motivs im Perlenkunst-Stil.

Optionaler Task-Name zu Anzeigezwecken. Maximal 100 Zeichen.

Die Anfrage war nicht akzeptabel. Häufige Ursachen:

• Fehlender Parameter: image_url und type sind beide erforderlich.
• Ungültiger type: type muss person oder other sein.
• 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 markiert: Das Eingabebild wurde durch die NSFW-moderation markiert.

Die Authentifizierung ist fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.

Nicht genügend Credits, um diese Task auszuführen, oder der API-Schlüssel gehört zu einem Konto mit kostenlosem Plan.

Das Eingabebild wurde durch die moderation für geistiges Eigentum markiert (Content flagged for intellectual property violation). Blockiert werden nur Enterprise-Konten mit aktivierter Filterung für geistiges Eigentum; es wird nichts berechnet.

Sie haben Ihre Ratenbegrenzung überschritten.

Die Prüfung auf geistiges Eigentum selbst konnte nicht abgeschlossen werden (Unable to perform intellectual property check, please try again). Enterprise-Konten mit aktivierter Filterung für geistiges Eigentum schlagen bei dieser Prüfung im Zweifel ab; es wird nichts berechnet – wiederholen Sie die Anfrage.

Die Aufgaben-ID einer Prototyp-Aufgabe, die über denselben OpenAPI-Endpunkt erstellt wurde. Der Prototyp muss vom selben Meshy-Konto erstellt worden sein und den Status SUCCEEDED erreicht haben.

Prototyp-Aufgaben, die über die Webapp erstellt wurden, werden nicht akzeptiert – der Build-Endpunkt akzeptiert nur Prototyp-Aufgaben, die von POST /openapi/creative-lab/fidget-pixel/v1/prototype erzeugt wurden, und lehnt jede andere Quelle mit 404 ab.

Optionaler Aufgabenname für Anzeigezwecke. Maximal 100 Zeichen.

Grundriss jedes Teils. Verfügbare Werte:

• square (Standard) — quadratische Teile auf einem quadratischen Raster.
• hex — sechseckige Teile auf einem hexagonalen Raster. Hex-Teile sind nur in 6 und 8 mm verfügbar.

Anzahl der Teile entlang jeder Seite des Bretts. Verfügbare Werte: 16 oder 32. Ein 32-Raster erhält mehr Details; ein 16-Raster bedeutet weniger, dafür größere Teile für dasselbe Motiv.

Kantenlänge jedes Teils in Millimetern. Verfügbare Werte: 6, 8 oder 10. Zusammen mit grid_size legt dies die gedruckte Brettgröße fest – zum Beispiel 32 × 8 mm ≈ 26 cm pro Seite. 10 ist bei shape: "hex" nicht verfügbar (die schräge Hex-Fläche überhängt bei den meisten FDM-Druckern für Endverbraucher).

Maximale Anzahl an Farben in der Palette, auf die das Bild quantisiert wird. Bereich: [1, 8]. Jede Farbe wird in Ihrem Slicer zu einem Filament.

Höhe jedes Teils in Millimetern. Bereich: [10, 80].

Vom Build zurückgegebenes Artefakt. Verfügbare Werte:

• 3mf (Standard) — gibt eine einzelne model.3mf unter model_urls.3mf zurück, mit einem Objekt pro Teil und der jeweiligen Teilfarbe, die an jedes Objekt angehängt ist.

Die Anfrage war nicht akzeptabel. Häufige Ursachen:

• Fehlender Parameter: input_task_id ist erforderlich.
• Ungültige UUID: input_task_id ist keine gültige UUID.
• Übergeordnete Aufgabe nicht abgeschlossen: Die referenzierte Prototyp-Aufgabe hat den Status SUCCEEDED noch nicht erreicht.
• Kein Kandidat: Die Prototyp-Aufgabe war erfolgreich, hat aber kein Pixel-Art-Bild erzeugt; erstellen Sie einen neuen Prototyp.
• Optionen außerhalb des zulässigen Bereichs: Eines der options-Felder liegt außerhalb der erlaubten Menge oder des erlaubten Bereichs — zum Beispiel options.grid_size must be 16 or 32, oder options.piece_size_mm=10 is not supported for shape=hex; hex pieces are available in 6 and 8 mm.
• Nicht unterstütztes Format: output.format muss 3mf sein.

Die Authentifizierung ist fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.

Unzureichende Credits, um diese Aufgabe auszuführen, oder der API-Schlüssel gehört zu einem Konto mit kostenlosem Tarif.

Das Bild des referenzierten Prototyps wurde durch die Prüfung auf geistiges Eigentum (moderation) markiert. Blockiert werden nur Enterprise-Konten mit aktivierter Filterung geistigen Eigentums; es werden keine Credits berechnet.

Die referenzierte Prototyp-Aufgabe existiert nicht, gehört einem anderen Benutzer oder wurde über die Webapp erstellt (nur im API-Modus erstellte Prototyp-Aufgaben können mit einem Build verkettet werden).

Sie haben Ihre Ratenbegrenzung überschritten.

Die Beurteilung des geistigen Eigentums des referenzierten Prototyps konnte nicht ermittelt werden (Unable to perform intellectual property check, please try again). Enterprise-Konten mit aktivierter Filterung geistigen Eigentums schlagen bei dieser Prüfung im Zweifel ab; es werden keine Credits berechnet — wiederholen Sie die Anfrage.

Eindeutige Kennung des abzurufenden Fidget-Pixel-Tasks.

id ist keine gültige UUID (Invalid ID).

Das Bild des Tasks wurde von der moderation für geistiges Eigentum markiert. Nur Enterprise-Konten mit aktivierter Filterung für geistiges Eigentum werden blockiert.

Der Task existiert nicht, gehört einem anderen Benutzer, oder seine Stufe stimmt nicht mit dem URL-Pfad überein.

Die Prüfung auf geistiges Eigentum konnte nicht abgeschlossen werden (Unable to perform intellectual property check, please try again); Enterprise-Konten mit aktivierter Filterung für geistiges Eigentum schlagen im Zweifel fehl (fail closed). Wiederholen Sie die Anfrage.

Eindeutige Kennung der abzubrechenden Fidget-Pixel-Aufgabe.

Die Anfrage war nicht akzeptabel. Häufige Ursachen:

• Ungültige ID: id ist keine gültige UUID.
• Endzustand: Die Aufgabe befindet sich bereits im Status SUCCEEDED, FAILED oder CANCELED und kann nicht abgebrochen werden.

Die Aufgabe existiert nicht, gehört einem anderen Benutzer, oder ihre Phase stimmt nicht mit dem URL-Pfad überein.

Eindeutiger Bezeichner des zu streamenden Fidget-Pixel-Tasks.

Entweder prototype oder build. Die Sammlung liefert nur Aufgaben zurück, deren Stufe mit der URL übereinstimmt — das Abrufen von /prototype liefert niemals Build-Aufgaben zurück und umgekehrt.

Seitenzahl für die Paginierung.

Begrenzung der Seitengröße. Maximal zulässig sind 100 Einträge.

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.

Eindeutige Kennung für die Aufgabe. Auch wenn wir als Implementierungsdetail eine k-sortierbare UUID für Task-IDs verwenden, solltest du keine Annahmen über das Format der ID treffen.

Typ der Aufgabe. Der Wert ist creative-lab-fidget-pixel-prototype.

Der bei der Erstellung der Aufgabe angegebene Aufgabenname. Leerer String, wenn kein Name angegeben wurde.

Status der Aufgabe. Mögliche Werte sind einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Fortschritt der Aufgabe. Wenn die Aufgabe noch nicht gestartet wurde, ist dieser Wert 0. Sobald die Aufgabe erfolgreich abgeschlossen wurde, wird er 100.

Zeitstempel, wann die Aufgabe erstellt wurde, in Millisekunden.

Zeitstempel, wann die Aufgabe gestartet wurde, in Millisekunden. Wenn die Aufgabe noch nicht gestartet wurde, ist dieser Wert null.

Zeitstempel, wann die Aufgabe beendet wurde, in Millisekunden. Wenn die Aufgabe noch nicht beendet wurde, ist dieser Wert null.

Zeitstempel, wann das Ergebnis der Aufgabe abläuft, in Millisekunden — 3 Tage nachdem die Aufgabe beendet wurde. Enterprise-Konten behalten API-Ergebnisse unbegrenzt (siehe Aufbewahrung von Assets); für sie ist dieser Zeitstempel auf etwa 100 Jahre in der Zukunft gesetzt.

Die Anzahl der vorausgehenden Aufgaben.

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

Die Anzahl der von dieser Aufgabe verbrauchten Credits. Einer Aufgabe, die SUCCEEDED erreicht, wird der volle Betrag für ihre Stufe berechnet. Eine Aufgabe, die nie erstellt wird (ein 4xx zum Zeitpunkt der Anfrage, einschließlich einer Ablehnung durch die moderation), wird überhaupt nicht berechnet. Eine Aufgabe, die FAILED erreicht, gibt 0 zurück — die Belastung wird erstattet. Ein Abbruch per DELETE erstattet nur, solange die Aufgabe noch PENDING ist; eine bereits IN_PROGRESS befindliche Aufgabe bleibt belastet, da die Arbeit bereits aufgewendet wurde.

Herunterladbare URLs für das von dieser Prototyp-Aufgabe erzeugte Pixel-Art-Bild. Derzeit gibt die API immer genau ein Bild zurück; das Feld ist ein Array, damit zukünftige Überarbeitungen mehrere Kandidaten anzeigen können, ohne eine Breaking Change zu verursachen. Leer, bis die Aufgabe SUCCEEDED erreicht.

Dies sind signierte URLs: rufe sie ohne einen Authorization-Header ab. Sie bleiben bis expires_at gültig, also 3 Tage nach finished_at, und ein erneutes Auslesen der Aufgabe innerhalb dieses Zeitfensters liefert dieselbe URL zurück, statt eine neu signierte. Lade die Dateien vorher selbst herunter und speichere sie — es gibt keine Möglichkeit, einen abgelaufenen Link zu erneuern.

Eindeutige Kennung für die Aufgabe.

Typ der Aufgabe. Der Wert ist creative-lab-fidget-pixel-build.

Der Aufgabenname, der bei der Erstellung der Aufgabe angegeben wurde. Leerer String, wenn kein Name angegeben wurde.

Status der Aufgabe. Mögliche Werte sind einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Fortschritt der Aufgabe. Wenn die Aufgabe noch nicht gestartet wurde, ist dieser Wert 0. Sobald die Aufgabe erfolgreich abgeschlossen wurde, wird er 100.

Zeitstempel der Erstellung der Aufgabe, in Millisekunden.

Zeitstempel des Starts der Aufgabe, in Millisekunden. null, bis die Aufgabe startet.

Zeitstempel des Abschlusses der Aufgabe, in Millisekunden. null, bis die Aufgabe abgeschlossen ist.

Zeitstempel, wann das Ergebnis der Aufgabe abläuft, in Millisekunden — 3 Tage nach Abschluss der Aufgabe. Enterprise-Konten behalten API-Ergebnisse unbegrenzt (siehe Aufbewahrung von Assets); für sie ist dieser Zeitstempel auf etwa 100 Jahre in der Zukunft festgelegt.

Die Anzahl der vorausgehenden Aufgaben. Nur relevant, wenn der Status PENDING ist.

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

Die Anzahl der von dieser Aufgabe verbrauchten Credits. Eine Aufgabe, die SUCCEEDED erreicht, wird mit dem vollen Betrag für ihre Stufe belastet. Eine Aufgabe, die nie erstellt wird (ein 4xx zum Zeitpunkt der Anfrage, einschließlich einer moderation-Ablehnung), wird überhaupt nicht belastet. Eine Aufgabe, die FAILED erreicht, gibt 0 zurück — die Belastung wird erstattet. Das Abbrechen über DELETE erstattet nur, solange die Aufgabe noch PENDING ist; eine bereits IN_PROGRESS befindliche Aufgabe bleibt belastet, da die Arbeit bereits geleistet wurde.

Herunterladbare URLs für das generierte Artefakt, indiziert nach Format. Enthält genau einen Eintrag — das über output.format der Build-Anfrage angeforderte Format. Leer, bis die Aufgabe SUCCEEDED erreicht.

Dies sind signierte URLs: Rufen Sie sie ohne Authorization-Header ab. Sie bleiben gültig bis expires_at, das ist 3 Tage nach finished_at, und ein erneutes Auslesen der Aufgabe innerhalb dieses Zeitfensters liefert dieselbe URL zurück statt einer neu signierten. Laden Sie die Dateien vorher selbst herunter und speichern Sie sie — es gibt keine Möglichkeit, einen abgelaufenen Link zu erneuern.