Creative Lab — Keycap API

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

Das Format wird durch Dekodieren der Bilddaten erkannt, nicht durch die Dateierweiterung der URL – eine URL ohne Erweiterung oder eine, die umleitet, funktioniert, solange die Bytes in ein unterstütztes Format dekodiert werden. HTTP-Weiterleitungen werden befolgt. Die EXIF-Ausrichtung wird normalisiert, sodass ein gedrehtes Handyfoto so verwendet wird, wie es aussieht.

Grenzen: mindestens 32 Pixel auf jeder Seite, maximal 178,956,970 Pixel insgesamt und maximal 20,000,000 Bytes nach dem Herunterladen. Bei einer Data URI gilt das Limit für die dekodierten Bytes, sodass die Quelldatei selbst bis zu dieser Größe sein kann – der Base64-Text ist etwa ein Drittel größer, was für Ihren Anfragekörper wichtig ist, nicht für dieses Limit. Eine Data URI muss einen image/*-Inhaltstyp und ;base64 deklarieren.

Es gibt zwei Möglichkeiten, das Bild bereitzustellen:

• Öffentlich zugängliche URL: Eine URL, die vom öffentlichen Internet aus zugänglich ist.
• Data URI: Eine Base64-kodierte Data URI des Bildes. Beispiel einer Data URI: data:image/jpeg;base64,<your base64-encoded image data>.

Optionaler Aufgabenname für Anzeigezwecke. Maximal 100 Zeichen.

Wenn auf true gesetzt, ist das in image_urls zurückgegebene Anzeigerendering ein transparentes RGBA-PNG mit entferntem Hintergrund, sodass Sie es auf jeden Hintergrund zusammensetzen können.

Dies gilt nur für das Anzeigerendering. Der Kandidat, den der Build-Endpunkt konsumiert, bleibt unberührt, 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 bereitgestellte image_url ist kein unterstütztes Format (.jpg, .jpeg, .png, .webp).
• Bildabmessungen außerhalb des Bereichs: Das Bild ist zu klein, überschreitet die maximale Dateigröße oder die maximale Pixelanzahl.
• Nicht erreichbare URL: Die image_url konnte nicht heruntergeladen werden (404 oder timeout).
• Ungültige Data URI: Der Base64-String ist fehlerhaft.
• Inhalt markiert: Das Eingabebild wurde durch NSFW moderation markiert.

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

Das Konto befindet sich im kostenlosen Plan (ein kostenpflichtiger Plan ist erforderlich, um Aufgaben zu erstellen) oder hat nicht genügend Credits.

Das Eingabebild wurde durch die moderation des geistigen Eigentums markiert.

Sie haben Ihre Ratenbegrenzung überschritten.

Ein unerwarteter serverseitiger Fehler ist aufgetreten – zum Beispiel war der Inhaltsmoderationsdienst nicht verfügbar, das Staging des Eingabebildes ist fehlgeschlagen oder die Aufgabe konnte nicht erstellt werden. In diesem Fall wird keine Aufgabe erstellt, sodass ein erneuter Versuch sicher ist.

Die Aufgaben-ID einer Prototyp-Aufgabe, die über diesen gleichen OpenAPI-Endpunkt erstellt wurde. Der Prototyp muss vom gleichen Meshy-Konto erstellt worden sein, muss SUCCEEDED erreicht haben und muss mindestens einen Kandidaten produziert haben.

Prototyp-Aufgaben, die über die Web-App erstellt wurden, werden nicht akzeptiert — der Build-Endpunkt akzeptiert nur Prototyp-Aufgaben, die durch POST /openapi/creative-lab/keycap/v1/prototype erstellt wurden, und lehnt jede andere Quelle mit 404 ab.

Der zu bauende Kandidat, entnommen aus dem candidate_ids Array der erfolgreichen Prototyp-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 aufgebaut werden soll. Derzeit ist der einzige verfügbare Wert cherry-mx-1x1-r1 — ein 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 skulptierten Kopfes in Millimetern: seine längste Dimension wird auf diesen Wert skaliert. Bereich: [10, 40]. Werte über etwa 32.9 können reduziert werden, damit der Kopf noch in das Schutzfußabdrucklimit der Basis passt, sodass die gelieferte längste Dimension kleiner als angefordert sein kann. Der angewendete Wert wird heute nicht im Aufgabenobjekt zurückgegeben — wenn Sie die tatsächlich erhaltene Größe bestätigen müssen, messen Sie den Begrenzungsrahmen des keycap-head Netzes im heruntergeladenen Modell.

Vertikaler Versatz, der auf den Kopf angewendet wird, bevor er auf der Basis platziert 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.
• Elternteil nicht erfolgreich: Die referenzierte Prototyp-Aufgabe hat SUCCEEDED noch nicht erreicht.
• Keine Kandidaten: Die Prototyp-Aufgabe war erfolgreich, hat aber keine Kandidaten produziert.
• Unbekannter Kandidat: candidate_id ist nicht einer der Kandidaten der Eingabeaufgabe.
• Optionen außerhalb des Bereichs: Eines der options-Felder lag außerhalb des erlaubten Bereichs oder Enum-Sets.

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

Das Konto befindet sich im kostenlosen Plan (ein kostenpflichtiger Plan ist erforderlich, um Aufgaben zu erstellen) oder hat nicht genügend Credits.

Die referenzierte Prototyp-Aufgabe existiert nicht, gehört einem anderen Benutzer oder wurde über die Web-App erstellt (nur API-Modus-Prototyp-Aufgaben werden in den Build übernommen).

Sie haben Ihre Ratenbegrenzung überschritten.

Ein unerwarteter serverseitiger Fehler ist aufgetreten — zum Beispiel war der Inhaltsmoderationsdienst nicht verfügbar, das Staging des Eingabebildes ist fehlgeschlagen oder die Aufgabe konnte nicht erstellt werden. In diesem Fall wird keine Aufgabe erstellt, sodass ein erneuter Versuch sicher ist.

Eindeutiger Bezeichner für die abzurufende Keycap-Aufgabe.

Eindeutiger Bezeichner für die abzubrechende Keycap-Aufgabe.

Die Aufgabe befindet sich bereits in einem Endzustand und kann nicht abgebrochen werden.

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

Ein unerwarteter serverseitiger Fehler trat beim Abbrechen auf. Die Aufgabe könnte abgebrochen worden sein oder nicht — lesen Sie sie erneut, um dies zu bestätigen, bevor Sie es erneut versuchen.

Eindeutiger Bezeichner für die Keycap-Aufgabe zum Streamen.

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

Seitennummer für die Paginierung.

Begrenzung der Seitengröße. Maximal erlaubt sind 100 Elemente.

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.

Eindeutiger Bezeichner für die Aufgabe. Obwohl wir eine k-sortierbare UUID für Task-IDs als Implementierungsdetail verwenden, sollten Sie keine Annahmen über das Format der ID machen.

Typ der Aufgabe. Der Wert ist creative-lab-keycap-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 diese Eigenschaft 0. Sobald die Aufgabe erfolgreich abgeschlossen ist, wird sie 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 diese Eigenschaft 0.

Zeitstempel, wann die Aufgabe abgeschlossen wurde, in Millisekunden. Wenn die Aufgabe noch nicht abgeschlossen ist, ist diese Eigenschaft 0.

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

Die Anzahl der vorhergehenden Aufgaben.

Fehlerdetails für fehlgeschlagene Aufgaben. Siehe Fehler für die vollständige task_error-Objektreferenz.

Die Anzahl der von dieser Aufgabe verbrauchten Credits. Eine Aufgabe, die SUCCEEDED erreicht, wird mit dem vollen Betrag für ihre Phase belastet. Eine Aufgabe, die nie erstellt wird (ein 4xx zur Anforderungszeit, einschließlich einer Moderationsablehnung), wird überhaupt nicht belastet. Eine Aufgabe, die FAILED erreicht, gibt 0 zurück — die Gebühr wird erstattet, einschließlich einer asynchronen Moderationssperre. Eine Stornierung über DELETE wird nur erstattet, solange die Aufgabe noch PENDING ist; eine bereits IN_PROGRESS befindliche Aufgabe bleibt belastet, da die Arbeit bereits geleistet wurde.

Herunterladbare URL des fertigen Keycap-Design-Renderings — wie der Kandidat als fertiges Keycap aussieht. Enthält einen einzigen Eintrag; image_urls[i] entspricht candidate_ids[i]. Leer, bis die Aufgabe SUCCEEDED erreicht. Die URL dient nur zur Anzeige; der Bau-Endpunkt verbraucht candidate_ids, nicht diese URLs. Gleicher URL-Lebenszyklus wie model_urls: signiert, kein Authorization-Header, gültig bis expires_at und stabil, wenn die Aufgabe erneut gelesen wird.

Opaque Kandidatenbezeichner, parallel zu image_urls. Übergeben Sie den Eintrag, der Ihrem gewählten Design entspricht, als candidate_id der Bauanforderung. Machen Sie keine Annahmen über das Format dieser IDs.

Eindeutiger Bezeichner für die Aufgabe.

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

Der bei der Erstellung 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 ist, wird dieser Wert 100.

Zeitstempel, wann die Aufgabe erstellt wurde, in Millisekunden.

Zeitstempel, wann die Aufgabe gestartet wurde, in Millisekunden.

Zeitstempel, wann die Aufgabe abgeschlossen wurde, in Millisekunden.

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

Die Anzahl der vorhergehenden Aufgaben. Nur sinnvoll, wenn der Status PENDING ist.

Fehlerdetails für fehlgeschlagene Aufgaben. Siehe Fehler für die vollständige task_error Objektreferenz.

Die Anzahl der von dieser Aufgabe verbrauchten Credits. Eine Aufgabe, die SUCCEEDED erreicht, wird mit dem vollen Betrag für ihre Stufe berechnet. Eine Aufgabe, die nie erstellt wird (ein 4xx zur Anforderungszeit, einschließlich einer Moderationsablehnung), wird überhaupt nicht berechnet. Eine Aufgabe, die FAILED erreicht, gibt 0 zurück — die Gebühr wird erstattet, einschließlich einer asynchronen Moderationsblockierung. Eine Stornierung über DELETE erstattet nur, solange die Aufgabe noch PENDING ist; eine Aufgabe, die bereits IN_PROGRESS ist, bleibt berechnet, da die Arbeit bereits geleistet wurde.

Herunterladbare URLs für die generierten Modellartefakte. Sowohl das GLB als auch das OBJ-Bundle werden im realen Millimetermaßstab, Y-oben, mit der Vorderseite des Keycaps in Richtung +Z exportiert. Netze sind als keycap-head und keycap-base benannt; wenn die Basis auf ein Musterfüllung zurückfällt, ist ein drittes Netz keycap-base-interior für die Stielhöhle ebenfalls vorhanden. Gehen Sie nicht davon aus, dass es genau zwei Netze gibt.

Dies sind signierte URLs: Abrufen ohne Authorization Header. Sie bleiben gültig bis expires_at, was 3 Tage nach finished_at ist, und das erneute Lesen der Aufgabe innerhalb dieses Fensters gibt die identische URL zurück, anstatt eine neu signierte. Laden Sie die Dateien selbst herunter und speichern Sie sie vor Ablauf — es gibt keine Möglichkeit, einen abgelaufenen Link zu aktualisieren.

Herunterladbare URLs für Zwischenprozessbilder, nach Art sortiert. Gleicher URL-Lebenszyklus wie model_urls: signiert, kein Authorization Header, gültig bis expires_at und stabil, wenn die Aufgabe erneut gelesen wird. Derzeit ausgegebene Arten:

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

Behandeln Sie die Schlüsselsammlung als offen; neue Arten können ohne eine Breaking-Änderung hinzugefügt werden.