Creative Lab — Keycap API

Ausgangsfoto, das Meshy in Keycap-Design-Bilder umwandeln soll. Wir unterstützen derzeit die Formate .jpg, .jpeg, .png und .webp.

Das Format wird durch Dekodierung der Bilddaten erkannt, nicht anhand der Dateiendung der URL — eine URL ohne Dateiendung oder eine, die weiterleitet, funktioniert, solange sich die Bytes zu einem unterstützten Format dekodieren lassen. HTTP-Weiterleitungen werden verfolgt. Die EXIF-Ausrichtung wird normalisiert, sodass ein gedrehtes Handyfoto so verwendet wird, wie es aussieht.

Grenzwerte: mindestens 32 Pixel pro Seite, höchstens 178.956.970 Pixel insgesamt und höchstens 20.000.000 Bytes nach dem Herunterladen. Bei einer Data URI gilt die Grenze für die dekodierten Bytes, sodass die Quelldatei selbst bis zu dieser Größe groß sein darf — es ist der Base64-Text, der etwa ein Drittel größer ist, was für Ihren Request-Body relevant ist, nicht für diese Grenze. Eine Data URI muss einen image/*-Content-Type und ;base64 angeben.

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-kodierte Data URI des Bildes. Beispiel für eine Data URI: data:image/jpeg;base64,<Ihre base64-kodierten Bilddaten>.

Optionaler Aufgabenname zu Anzeigezwecken. Maximal 100 Zeichen.

Wenn dies auf true gesetzt ist, ist der in image_urls zurückgegebene Anzeige-Render ein transparentes RGBA-PNG mit entferntem Hintergrund, sodass Sie es auf einen beliebigen Hintergrund legen können.

Dies gilt nur für den Anzeige-Render. Der Kandidat, den der Build-Endpunkt verwendet, ist davon nicht betroffen, sodass das 3D-Ergebnis in beiden Fällen identisch ist.

Die Anfrage war nicht akzeptabel. Häufige Ursachen:

• Fehlender Parameter: image_url ist erforderlich.
• Ungültiges Bildformat: Die angegebene image_url liegt nicht in einem unterstützten Format vor (.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 markiert: Das Eingabebild wurde durch die NSFW-moderation markiert.

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

Das Konto befindet sich im kostenlosen Plan (für das Erstellen von Aufgaben ist ein kostenpflichtiger Plan erforderlich) oder verfügt über nicht ausreichende Credits.

Das Eingabebild wurde durch die moderation für geistiges Eigentum markiert.

Sie haben Ihre Ratenbegrenzung überschritten.

Ein unerwarteter serverseitiger Fehler ist aufgetreten — zum Beispiel war der Content-moderation-Dienst nicht verfügbar, das Bereitstellen des Eingabebilds ist fehlgeschlagen, oder die Aufgabe konnte nicht erstellt werden. In diesem Fall wird keine Aufgabe erstellt, sodass ein erneuter Versuch unbedenklich ist.

Die Task-ID einer über denselben OpenAPI-Endpunkt erstellten Prototype-Aufgabe. Der Prototyp muss vom selben Meshy-Konto erstellt worden sein, muss den Status SUCCEEDED erreicht haben und muss mindestens einen Kandidaten hervorgebracht haben.

Über die Webapp erstellte Prototype-Aufgaben werden nicht akzeptiert – der Build-Endpunkt akzeptiert nur Prototype-Aufgaben, die von POST /openapi/creative-lab/keycap/v1/prototype erzeugt wurden, und lehnt jede andere Quelle mit 404 ab.

Der zu bauende Kandidat, entnommen aus dem candidate_ids-Array der erfolgreichen Prototype-Aufgabe. Muss zu dieser Aufgabe gehören; jeder andere Wert wird mit 400 abgelehnt.

Optionaler Aufgabenname für Anzeigezwecke. Maximal 100 Zeichen.

Die Keycap-Basis, auf der gebaut werden soll. Derzeit ist der einzige verfügbare Wert cherry-mx-1x1-r1 – eine Standard-Cherry-MX-Profil-1u-Keycap. 3–5 zusätzliche gängige Standardgrößen sind geplant; benutzerdefinierte Größen werden nicht unterstützt.

Zielgröße des gestalteten Kopfes in Millimetern: seine längste Abmessung wird auf diesen Wert skaliert. Bereich: [10, 40]. Werte über etwa 32,9 können reduziert werden, damit der Kopf weiterhin innerhalb der Schutz-Grundflächenbegrenzung der Basis liegt, sodass die gelieferte längste Abmessung kleiner sein kann als angefordert. Der angewendete Wert wird derzeit nicht im Task-Objekt zurückgemeldet – wenn Sie die tatsächlich erhaltene Größe überprüfen möchten, messen Sie den Begrenzungsrahmen des keycap-head-Netzes im heruntergeladenen Modell.

Vertikaler Versatz, der auf den Kopf angewendet wird, bevor er auf der Basis aufgesetzt wird, in Millimetern. Bereich: [-5, 5].

Die Anfrage war nicht akzeptabel. Häufige Ursachen:

• Fehlender Parameter: input_task_id und candidate_id sind erforderlich.
• Ungültige UUID: Die input_task_id ist keine gültige UUID.
• Übergeordnete Aufgabe nicht erfolgreich: Die referenzierte Prototype-Aufgabe hat noch nicht den Status SUCCEEDED erreicht.
• Keine Kandidaten: Die Prototype-Aufgabe war erfolgreich, hat aber keine Kandidaten hervorgebracht.
• Unbekannter Kandidat: candidate_id gehört nicht zu den Kandidaten der Eingabeaufgabe.
• Optionen außerhalb des zulässigen Bereichs: Eines der options-Felder lag außerhalb seines zulässigen Bereichs oder Enum-Satzes.

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

Das Konto befindet sich im kostenlosen Plan (für das Erstellen von Aufgaben ist ein kostenpflichtiger Plan erforderlich) oder verfügt über nicht ausreichende Credits.

Die referenzierte Prototype-Aufgabe existiert nicht, gehört einem anderen Benutzer, oder wurde über die Webapp erstellt (nur Prototype-Aufgaben im API-Modus können in ein Build übergehen).

Sie haben Ihre Ratenbegrenzung überschritten.

Es ist ein unerwarteter serverseitiger Fehler aufgetreten – zum Beispiel war der Content-Moderation-Dienst nicht verfügbar, das Bereitstellen des Eingabebilds ist fehlgeschlagen, oder die Aufgabe konnte nicht erstellt werden. In diesem Fall wird keine Aufgabe erstellt, sodass ein erneuter Versuch unbedenklich ist.

Eindeutige Kennung des abzurufenden Keycap-Tasks.

Eindeutige Kennung der abzubrechenden Keycap-Aufgabe.

Die Aufgabe befindet sich bereits in einem endgültigen Status und kann nicht abgebrochen werden.

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

Beim Abbrechen ist ein unerwarteter serverseitiger Fehler aufgetreten. Die Aufgabe wurde möglicherweise abgebrochen oder auch nicht — lesen Sie sie erneut aus, um dies vor einem erneuten Versuch zu bestätigen.

Eindeutige Kennung der zu streamenden Keycap-Aufgabe.

Entweder prototype oder build. Die Auflistung liefert nur Tasks zurück, deren Stufe mit der URL übereinstimmt — das Abrufen von /prototype liefert niemals Build-Tasks 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 Erstellungszeitpunkt in aufsteigender Reihenfolge.
• -created_at: Sortierung nach Erstellungszeitpunkt in absteigender Reihenfolge.

Eindeutiger Bezeichner für die Aufgabe. Wir verwenden als Implementierungsdetail eine k-sortierbare UUID für Task-IDs, du solltest jedoch keine Annahmen über das Format der ID treffen.

Typ der Aufgabe. Der Wert ist creative-lab-keycap-prototype.

Der beim Erstellen der Aufgabe angegebene Aufgabenname. Leerer String, wenn kein Name angegeben wurde.

Status der Aufgabe. Mögliche Werte sind 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 0.

Zeitstempel, wann die Aufgabe abgeschlossen wurde, in Millisekunden. Wenn die Aufgabe noch nicht abgeschlossen ist, ist dieser Wert 0.

Zeitstempel, wann das Ergebnis der Aufgabe abläuft, in Millisekunden.

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. Bei 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 moderation-Ablehnung), wird überhaupt nicht berechnet. Eine Aufgabe, die FAILED erreicht, gibt 0 zurück — der Betrag wird erstattet, einschließlich eines asynchronen moderation-Blocks. Ein Abbruch per DELETE erstattet nur, solange die Aufgabe noch PENDING ist; eine bereits IN_PROGRESS befindliche Aufgabe bleibt berechnet, da die Arbeit bereits geleistet wurde.

Herunterladbare URL des gerenderten fertigen Keycap-Designs — wie der Kandidat als fertiger Keycap aussieht. Enthält genau einen Eintrag; image_urls[i] entspricht candidate_ids[i]. Leer, bis die Aufgabe SUCCEEDED erreicht. Die URL dient nur zur Anzeige; der Build-Endpunkt verarbeitet candidate_ids, nicht diese URLs. Gleicher URL-Lebenszyklus wie model_urls: signiert, kein Authorization-Header, gültig bis expires_at, und stabil beim erneuten Lesen der Aufgabe.

Undurchsichtige Kandidaten-Bezeichner, parallel zu image_urls. Übergib den Eintrag, der deinem gewählten Design entspricht, als candidate_id der Build-Anfrage. Triff keine Annahmen über das Format dieser IDs.

Eindeutige Kennung für die Task.

Typ der Task. Der Wert ist creative-lab-keycap-build.

Der beim Erstellen der Task angegebene Name. Leerer String, wenn kein Name angegeben wurde.

Status der Task. Mögliche Werte sind PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Fortschritt der Task. Wenn die Task noch nicht gestartet wurde, hat diese Eigenschaft den Wert 0. Sobald die Task erfolgreich war, wird dieser Wert 100.

Zeitstempel, wann die Task erstellt wurde, in Millisekunden.

Zeitstempel, wann die Task gestartet wurde, in Millisekunden.

Zeitstempel, wann die Task beendet wurde, in Millisekunden.

Zeitstempel, wann das Ergebnis der Task abläuft, in Millisekunden.

Die Anzahl vorausgehender Tasks. Nur relevant, wenn der Status PENDING ist.

Fehlerdetails für fehlgeschlagene Tasks. Die vollständige Referenz zum task_error-Objekt finden Sie unter Fehler.

Die Anzahl der von dieser Task verbrauchten Credits. Einer Task, die SUCCEEDED erreicht, wird der volle Betrag für ihre Phase berechnet. Eine Task, die nie erstellt wird (ein 4xx zum Zeitpunkt der Anfrage, einschließlich einer Ablehnung durch die moderation), wird überhaupt nicht berechnet. Eine Task, die FAILED erreicht, gibt 0 zurück — die Gebühr wird erstattet, einschließlich eines asynchronen moderation-Blocks. Ein Abbrechen über DELETE erstattet die Gebühr nur, solange die Task noch PENDING ist; eine bereits IN_PROGRESS befindliche Task bleibt kostenpflichtig, da die Arbeit bereits geleistet wurde.

Herunterladbare URLs für die generierten Modell-Artefakte. Sowohl das GLB- als auch das OBJ-Bundle werden im realen Maßstab in Millimetern, mit Y-nach-oben, exportiert, wobei die Vorderseite der Keycap nach +Z zeigt. Die Netze heißen keycap-head und keycap-base; wenn die Basis auf eine Musterfüllung zurückgreift, ist zusätzlich ein drittes Netz keycap-base-interior für den Stem-Hohlraum vorhanden. Gehen Sie nicht davon aus, dass es genau zwei Netze gibt.

Dies sind signierte URLs: Rufen Sie sie ohne einen Authorization-Header ab. Sie bleiben gültig bis expires_at, was 3 Tage nach finished_at liegt, und ein erneutes Lesen der Task 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.

Herunterladbare URLs für zwischengeschaltete Prozessbilder, geschlüsselt nach Art. Gleicher URL-Lebenszyklus wie bei model_urls: signiert, kein Authorization-Header, gültig bis expires_at und stabil bei erneutem Lesen der Task. Aktuell ausgegebene Arten:

• head_design — das vom Build verwendete Designbild des gewählten Kandidaten (immer vorhanden).
• composite — das fertige Anzeige-Rendering der ausgewählten Keycap des gewählten Kandidaten (vorhanden, wenn verfügbar).
• base_canvas — die bemalte Keycap-Basis-Leinwand (vorhanden, wenn verfügbar).

Betrachten Sie die Menge der Schlüssel als offen; neue Arten können hinzugefügt werden, ohne eine breaking change darzustellen.