Creative Lab Keycap API

Das Foto, das in ein Keycap-Design umgewandelt werden soll, als öffentliche URL oder als Data URI (data:image/jpeg;base64,<Ihre base64-kodierten Bilddaten>).

Das Bild muss eine JPG-, JPEG-, PNG- oder WebP-Datei von maximal 20 MB (20.000.000 Byte) sein. Jede Seite muss mindestens 32 Pixel groß sein, und das Bild darf insgesamt höchstens 178.956.970 Pixel haben. Ein Bild außerhalb dieser Grenzen liefert 400 zurück.

Meshy erkennt das Format anhand der Bilddaten, nicht anhand der Dateiendung in der URL. Eine URL ohne Dateiendung funktioniert, und Meshy folgt HTTP-Weiterleitungen. Meshy wendet die EXIF-Ausrichtung an, sodass ein gedrehtes Handyfoto so herauskommt, wie es aussieht.

Eine Data URI muss base64-kodiert sein und einen Bildtyp angeben, wie zum Beispiel data:image/png;base64,..., und das dekodierte Bild muss JPEG, PNG oder WebP sein. Das Limit von 20 MB gilt für das dekodierte Bild, sodass der base64-Text etwa ein Drittel größer sein kann.

Ein Name für die Aufgabe, bis zu 100 Zeichen. Er wird im Feld name der Aufgabe zurückgegeben. Ein längerer Name liefert 400 zurück.

Ob der Hintergrund aus dem Prototyp-Bild entfernt werden soll. true liefert ein transparentes RGBA-PNG zurück, sodass Sie den Keycap vor jedem beliebigen Hintergrund platzieren können. Wenn Meshy den Hintergrund nicht entfernen kann, wird das Bild mit seinem Hintergrund zurückgegeben, und die Aufgabe ist trotzdem erfolgreich.

Das Kopfdesign, das der Build in 3D umwandelt, behält seinen Hintergrund in jedem Fall. Der Build bemalt die Keycap-Basis anhand des Bildes in image_urls, ohne dessen Hintergrund, falls Sie true gesendet haben. Der Build gibt dieses Bild als process_image_urls.composite zurück.

Die Anfrage kann nicht ausgeführt werden. Zum Beispiel:

• image_url fehlt.
• Das Bild ist keine JPG-, JPEG-, PNG- oder WebP-Datei.
• Das Bild ist zu klein, größer als 20 MB oder überschreitet die maximale Pixelanzahl.
• Meshy kann das Bild nicht herunterladen, zum Beispiel weil die URL 404 zurückgibt oder eine Zeitüberschreitung auftritt.
• Die Data URI ist kein gültiges base64.
• Das Bild wurde als NSFW eingestuft.

Die Fehlermeldung gibt an, welches Problem gefunden wurde. Beheben Sie die Anfrage und senden Sie sie erneut.

Der API-Schlüssel fehlt oder ist ungültig. Überprüfen Sie den Authorization-Header.

Einer der folgenden Fälle trifft zu:

• Das Konto verfügt nicht über genügend Credits.
• Der API-Schlüssel, der Arbeitsbereich oder das Mitglied hat das Credit-Limit erreicht.
• Das Konto nutzt den kostenlosen Plan.

Überprüfen Sie Ihre Credits und Ihren Plan, und versuchen Sie es erneut.

Ihr Team hat IP-Filterung aktiviert, und Meshy hat das Bild wegen geistigen Eigentums Dritter markiert. Senden Sie ein Bild, für das Sie die Nutzungsrechte besitzen.

Eines dieser Limits wurde erreicht:

• Sie haben mehr Anfragen gesendet, als Ihre Ratenbegrenzung erlaubt. Warten Sie einige Sekunden und versuchen Sie es erneut. Siehe Ratenbegrenzungen.
• Zu viele Ihrer Aufgaben sind in der Warteschlange oder werden gerade ausgeführt. Warten Sie, bis einige abgeschlossen sind, und versuchen Sie es erneut.
• Bei einem unbegrenzten Plan ohne verbleibende Credits haben Sie die Anzahl der Aufgaben erreicht, die ohne Credits laufen können. Warten Sie, bis eine Aufgabe abgeschlossen ist, oder fügen Sie Credits hinzu.

Bei Meshy ist ein Serverfehler aufgetreten, zum Beispiel weil die Inhaltsmoderation oder die Prüfung des geistigen Eigentums nicht ausgeführt werden konnte oder Meshy das Bild nicht speichern konnte. Meshy erstellt die Aufgabe nicht und erstattet alle dafür berechneten Credits zurück. Versuchen Sie die Anfrage erneut.

Die ID des zu bauenden Prototyp-Tasks. Sie muss zu einem Task gehören, den Ihr Konto mit POST /openapi/creative-lab/keycap/v1/prototype erstellt hat, mit dem Status SUCCEEDED.

Eine ID, die keinem Ihrer Keycap-Prototyp-Tasks aus der API entspricht, liefert 404, einschließlich eines in der Web-App erstellten Prototyps.

Der zu bauende Kandidat, aus dem candidate_ids-Array des Prototyp-Tasks. Ein Wert, der nicht in diesem Array enthalten ist, liefert 400.

Ein Name für den Task, bis zu 100 Zeichen. Er wird im name-Feld des Tasks zurückgegeben. Ein längerer Name liefert 400.

Die Keycap-Basis, auf der gebaut werden soll. Der einzige Wert ist cherry-mx-1x1-r1, eine Standard-Cherry-MX-Profil-1u-Keycap. Benutzerdefinierte Größen werden nicht unterstützt, und jeder andere Wert liefert 400.

Die Größe des Kopfes entlang seiner längsten Abmessung, in Millimetern, von 10 bis 40. Meshy skaliert den Kopf so, dass seine längste Abmessung diesem Wert entspricht. Ein Wert außerhalb des Bereichs liefert 400.

Bei einem Wert über etwa 32.9 reduziert Meshy möglicherweise die Größe, damit der Kopf in die Schutz-Grundfläche der Basis passt. Der Kopf kann dann kleiner ausfallen, als Sie angefordert haben. Das Task-Objekt gibt die von Meshy angewandte Größe nicht zurück. Um sie zu prüfen, messen Sie den Begrenzungsrahmen des keycap-head-Netzes im Modell.

Der vertikale Versatz, der auf den Kopf angewendet wird, bevor Meshy ihn auf der Basis platziert, in Millimetern, von -5 bis 5. Ein Wert außerhalb des Bereichs liefert 400.

Die Anfrage kann nicht ausgeführt werden. Zum Beispiel:

• input_task_id fehlt oder ist keine gültige Task-ID.
• Der Status des Prototyp-Tasks ist nicht SUCCEEDED. Wenn er noch läuft, warten Sie und versuchen Sie es erneut. Wenn er fehlgeschlagen oder abgebrochen wurde, erstellen Sie einen neuen Prototyp-Task.
• Der Prototyp-Task war erfolgreich, hat aber keine Kandidaten. Erstellen Sie einen neuen Prototyp-Task.
• candidate_id fehlt oder ist nicht in den candidate_ids des Prototyp-Tasks enthalten. Senden Sie einen Wert aus diesem Array.
• Ein Feld in options liegt außerhalb des gültigen Bereichs, oder base_model ist kein verfügbarer Wert.

Die Fehlermeldung gibt an, welches Problem gefunden wurde.

Der API-Schlüssel fehlt oder ist ungültig. Überprüfen Sie den Authorization-Header.

Einer dieser Fälle trifft zu:

• Das Konto verfügt nicht über genügend Credits.
• Der API-Schlüssel, Arbeitsbereich oder das Mitglied hat sein Credit-Limit erreicht.
• Das Konto nutzt den kostenlosen Plan.

Prüfen Sie Ihre Credits und Ihren Plan und versuchen Sie es erneut.

input_task_id entspricht keinem Keycap-Prototyp-Task, den Ihr Konto über die API erstellt hat. Ein in der Web-App erstellter Prototyp liefert ebenfalls 404. Senden Sie die result-ID aus einer Prototyp-Erstellungsantwort.

Eines dieser Limits wurde erreicht:

• Sie haben mehr Anfragen gesendet, als Ihre Ratenbegrenzung zulässt. Warten Sie einige Sekunden und versuchen Sie es erneut. Siehe Ratenbegrenzungen.
• Zu viele Ihrer Tasks sind in der Warteschlange oder laufen bereits. Warten Sie, bis einige abgeschlossen sind, und versuchen Sie es erneut.
• Bei einem unbegrenzten Plan ohne verbleibende Credits haben Sie die Anzahl der Tasks erreicht, die ohne Credits laufen können. Warten Sie, bis ein Task abgeschlossen ist, oder fügen Sie Credits hinzu.

Meshy konnte den Task aufgrund eines Serverfehlers nicht erstellen. Meshy erstattet alle berechneten Credits zurück. Versuchen Sie die Anfrage erneut.

Die Task-ID aus der Create-Antwort.

id ist keine gültige Task-ID. Senden Sie die result-ID aus der Create-Antwort.

Ihr Team hat IP Filtering aktiviert, und Meshy hat das Bild des Prototype-Tasks wegen geistigen Eigentums Dritter markiert. Build-Tasks und Teams im Enterprise-Plan erhalten diesen Fehler nicht. Erstellen Sie einen Prototype-Task mit einem Bild, an dem Sie die Nutzungsrechte besitzen.

Es gehört kein Keycap-Task mit dieser ID zu Ihrem Konto, oder die Stage des Tasks stimmt nicht mit dem Pfad überein. Prüfen Sie die ID und verwenden Sie /prototype oder /build passend zum Task.

Meshy konnte die Prüfung auf geistiges Eigentum nicht durchführen. Wiederholen Sie die Anfrage.

Die ID des abzubrechenden Tasks.

Einer der folgenden Fälle trifft zu:

• id ist keine gültige Task-ID. Senden Sie die result-ID aus der Erstellungsantwort.
• Der Task hat bereits einen finalen Status (SUCCEEDED, FAILED oder CANCELED) und kann daher nicht abgebrochen werden.

Es gehört kein Keycap-Task mit dieser ID zu Ihrem Konto, oder die Stufe des Tasks stimmt nicht mit dem Pfad überein. Überprüfen Sie die ID und verwenden Sie /prototype oder /build, um den Task zuzuordnen.

Bei Meshy ist beim Abbrechen des Tasks ein Serverfehler aufgetreten, sodass der Task möglicherweise abgebrochen wurde oder auch nicht. Rufen Sie den Task ab, um dessen status zu prüfen, bevor Sie es erneut versuchen.

Die Task-ID aus der Erstellungsantwort.

Die aufzulistende Stufe, prototype oder build.

Die zurückzugebende Seite, von 1 bis 255. 0 gibt die erste Seite zurück. Ein Wert außerhalb von 0 bis 255 gibt 400 zurück.

Anzahl der Tasks pro Seite, bis zu 100. Ein Wert von 101 bis 255 gibt 100 Tasks zurück, und 0 verwendet den Standardwert. Ein Wert außerhalb von 0 bis 255 gibt 400 zurück.

Die Sortierreihenfolge.

Verfügbare Werte:

• -created_at: neueste zuerst
• +created_at: älteste zuerst

Die Task-ID. Verlassen Sie sich nicht auf ihr Format.

Der Task-Typ, immer creative-lab-keycap-prototype.

Der name, den Sie beim Erstellen des Tasks gesendet haben, oder "", wenn Sie keinen gesendet haben.

Der Status des Tasks.

Verfügbare Werte:

• PENDING: wartet in der Warteschlange
• IN_PROGRESS: Ergebnis wird generiert
• SUCCEEDED: final, mit Ergebnis
• FAILED: final, mit dem Grund in task_error
• CANCELED: final, ohne Ergebnis

Prozentsatz der erledigten Arbeit, von 0 bis 100. Der Wert ist 0, bis der Task beginnt, und 100, wenn er erfolgreich ist.

Zeitpunkt, zu dem der Task erstellt wurde, in Unix-Millisekunden.

Zeitpunkt, zu dem ein Worker den Task gestartet hat, in Unix-Millisekunden. Bis dahin null.

Zeitpunkt, zu dem der Task einen finalen Status erreicht hat, in Unix-Millisekunden. Bis dahin null.

Zeitpunkt, zu dem das Ergebnis des Tasks abläuft, in Unix-Millisekunden. Das ist 3 Tage nach finished_at, oder 3 Tage nach created_at, solange der Task noch nicht abgeschlossen ist. Für Enterprise-Konten, die API-Ergebnisse unbegrenzt aufbewahren, liegt dieser Zeitpunkt etwa 100 Jahre später. Siehe Aufbewahrung von Assets.

Die Position des Tasks in der Warteschlange, solange er PENDING ist. 1 bedeutet, dass er als Nächstes startet. 0, nachdem der Task die Warteschlange verlassen hat, und in Listenergebnissen immer 0.

Warum der Task fehlgeschlagen ist. null, es sei denn, status ist FAILED. Siehe Fehler.

Anzahl der für den Task berechneten Credits, nach einer eventuellen Rückerstattung. Eine Anfrage, die einen Fehler zurückgibt, wird nicht berechnet. Ein fehlgeschlagener Task hat den Wert 0, da Meshy ihn erstattet. Ein Abbruch erstattet einen Task nur, solange er PENDING ist. Wenn Meshy die Belastung nicht auslesen kann, lässt eine Get- oder Stream-Antwort das Feld weg, und eine Listenanfrage gibt 500 zurück. Wiederholen Sie die Anfrage in diesem Fall.

Download-URLs für das Bild des fertigen Keycaps. Das Array enthält eine URL, nachdem der Task erfolgreich war, und ist bis dahin leer. image_urls[i] zeigt den Kandidaten aus candidate_ids[i].

Diese URLs dienen der Anzeige. Der Build-Endpunkt erwartet einen Eintrag aus candidate_ids, keine URL. Es handelt sich um signierte URLs, rufen Sie sie daher ohne Authorization-Header ab. Sie bleiben bis expires_at gültig, und ein erneutes Abrufen des Tasks liefert dieselben URLs.

IDs der Kandidaten, in derselben Reihenfolge wie image_urls. Um einen Kandidaten zu bauen, senden Sie dessen ID als candidate_id in der Build-Anfrage. Verlassen Sie sich nicht auf das Format dieser IDs.

Die Task-ID. Verlassen Sie sich nicht auf ihr Format.

Der Task-Typ, immer creative-lab-keycap-build.

Der name, den Sie beim Erstellen des Tasks gesendet haben, oder "", wenn Sie keinen gesendet haben.

Der Status des Tasks.

Verfügbare Werte:

• PENDING: wartet in der Warteschlange
• IN_PROGRESS: generiert das Ergebnis
• SUCCEEDED: final, mit dem Ergebnis
• FAILED: final, mit dem Grund in task_error
• CANCELED: final, ohne Ergebnis

Prozentsatz der erledigten Arbeit, von 0 bis 100. Er ist 0, bis der Task startet, und 100, wenn er erfolgreich ist.

Zeitpunkt, zu dem der Task erstellt wurde, in Unix-Millisekunden.

Zeitpunkt, zu dem ein Worker den Task gestartet hat, in Unix-Millisekunden. Bis dahin null.

Zeitpunkt, zu dem der Task einen finalen Status erreicht hat, in Unix-Millisekunden. Bis dahin null.

Zeitpunkt, zu dem das Ergebnis des Tasks abläuft, in Unix-Millisekunden. Das ist 3 Tage nach finished_at, oder 3 Tage nach created_at, bis der Task abgeschlossen ist. Bei Enterprise-Konten, die API-Ergebnisse unbegrenzt aufbewahren, liegt er etwa 100 Jahre später. Siehe Aufbewahrung von Assets.

Die Position des Tasks in der Warteschlange, solange er PENDING ist. 1 bedeutet, dass er als Nächstes startet. 0, nachdem der Task die Warteschlange verlassen hat, und immer 0 in Listenergebnissen.

Warum der Task fehlgeschlagen ist. null, es sei denn, status ist FAILED. Siehe Fehler.

Anzahl der für den Task berechneten Credits, nach einer eventuellen Rückerstattung. Eine Anfrage, die einen Fehler zurückgibt, wird nicht berechnet. Ein fehlgeschlagener Task hat 0, da Meshy ihn zurückerstattet. Ein Abbruch erstattet einen Task nur, solange er PENDING ist. Wenn Meshy die Belastung nicht auslesen kann, lässt eine Get- oder Stream-Antwort das Feld weg, und eine Listenanfrage gibt 500 zurück. In diesem Fall wiederholen Sie die Anfrage.

Download-URLs für das 3D-Modell. Meshy exportiert die GLB-Datei und das OBJ-Bundle im Maßstab 1:1 in Millimetern, Y-up, wobei die Vorderseite der Keycap in Richtung +Z zeigt.

Das Modell hat Netze mit den Namen keycap-head und keycap-base. Wenn Meshy auf eine Musterfüllung für die Basis zurückgreift, hat das Modell außerdem ein keycap-base-interior-Netz für den Stößel-Hohlraum. Gehen Sie nicht davon aus, dass das Modell genau zwei Netze hat.

Dies sind signierte URLs, rufen Sie sie also ohne einen Authorization-Header ab. Sie bleiben bis expires_at gültig, und ein erneutes Abrufen des Tasks davor liefert dieselben URLs zurück. Eine abgelaufene URL kann nicht erneuert werden, laden Sie die Dateien also vorher herunter und speichern Sie sie.

Download-URLs für Bilder aus den Schritten des Builds, nach Art indiziert. Wie bei model_urls handelt es sich um signierte URLs, rufen Sie sie also ohne einen Authorization-Header ab. Sie bleiben bis expires_at gültig, und ein erneutes Abrufen des Tasks liefert dieselben URLs zurück.

Es kann folgende Schlüssel enthalten:

• head_design: das Designbild des gewählten Kandidaten, das der Build in 3D umgewandelt hat. Immer vorhanden.
• composite: das Bild der fertigen Keycap für den gewählten Kandidaten, aus dem der Build die Basis bemalt hat. Kann fehlen.
• base_canvas: die bemalte Keycap-Basis. Kann fehlen.

Meshy kann Schlüssel hinzufügen, ignorieren Sie also einen Schlüssel, den Sie nicht erkennen.