Creative Lab — Keycap API

Foto sorgente che Meshy trasformerà in immagini di design del keycap. Attualmente supportiamo i formati .jpg, .jpeg, .png e .webp.

Il formato viene rilevato decodificando i dati dell'immagine, non dall'estensione del file nell'URL — un URL senza estensione, o che effettua un reindirizzamento, funziona purché i byte vengano decodificati in un formato supportato. I reindirizzamenti HTTP vengono seguiti. L'orientamento EXIF viene normalizzato, quindi una foto scattata da telefono e ruotata viene utilizzata come appare visivamente.

Limiti: almeno 32 pixel per lato, al massimo 178.956.970 pixel in totale e al massimo 20.000.000 byte una volta scaricata. Per una Data URI il limite si applica ai byte decodificati, quindi il file sorgente stesso può arrivare a quella dimensione — è il testo base64 a essere circa un terzo più grande, il che è rilevante per il corpo della richiesta, non per questo limite. Una Data URI deve dichiarare un content type image/* e ;base64.

Ci sono due modi per fornire l'immagine:

• URL pubblicamente accessibile: un URL accessibile dalla rete internet pubblica.
• Data URI: una data URI dell'immagine codificata in base64. Esempio di data URI: data:image/jpeg;base64,<i tuoi dati immagine codificati in base64>.

Nome opzionale dell'attività a scopo di visualizzazione. Massimo 100 caratteri.

Quando impostato su true, il render di visualizzazione restituito in image_urls è un PNG RGBA trasparente con lo sfondo rimosso, in modo da poterlo comporre su qualsiasi sfondo.

Questo si applica solo al render di visualizzazione. Il candidato consumato dall'endpoint di build non è influenzato, quindi il risultato 3D è identico in entrambi i casi.

La richiesta non era accettabile. Cause comuni:

• Parametro mancante: image_url è obbligatorio.
• Formato immagine non valido: l'image_url fornito non è in un formato supportato (.jpg, .jpeg, .png, .webp).
• Dimensioni dell'immagine fuori intervallo: l'immagine è troppo piccola, supera la dimensione massima del file o supera il numero massimo di pixel.
• URL non raggiungibile: non è stato possibile scaricare l'image_url (404 o timeout).
• Data URI non valida: la stringa base64 è malformata.
• Contenuto segnalato: l'immagine in ingresso è stata segnalata dalla moderation NSFW.

Autenticazione non riuscita. Controlla la tua chiave API.

L'account è su un piano gratuito (è richiesto un piano a pagamento per creare attività) oppure ha crediti insufficienti.

L'immagine in ingresso è stata segnalata dalla moderation sulla proprietà intellettuale.

Hai superato il tuo limite di frequenza.

Si è verificato un errore lato server imprevisto — ad esempio il servizio di content moderation non era disponibile, la fase di staging dell'immagine in ingresso non è riuscita, oppure non è stato possibile creare l'attività. In questo caso non viene creata alcuna attività, quindi è sicuro riprovare.

L'ID dell'attività di un'attività di prototipo creata tramite questo stesso endpoint OpenAPI. Il prototipo deve essere stato creato dallo stesso account Meshy, deve aver raggiunto lo stato SUCCEEDED e deve aver prodotto almeno un candidato.

Le attività di prototipo create tramite la webapp non sono accettate — l'endpoint di build accetta solo attività di prototipo prodotte da POST /openapi/creative-lab/keycap/v1/prototype e rifiuta qualsiasi altra origine con 404.

Il candidato da costruire, prelevato dall'array candidate_ids dell'attività di prototipo riuscita. Deve appartenere a quell'attività; qualsiasi altro valore viene rifiutato con 400.

Nome facoltativo dell'attività per scopi di visualizzazione. Massimo 100 caratteri.

La base del keycap su cui costruire. Attualmente l'unico valore disponibile è cherry-mx-1x1-r1 — un keycap standard 1u con profilo Cherry MX. Sono previste 3–5 dimensioni standard mainstream aggiuntive; le dimensioni personalizzate non sono supportate.

Dimensione target della testa scolpita, in millimetri: la sua dimensione più lunga viene scalata a questo valore. Intervallo: [10, 40]. Valori superiori a circa 32.9 possono essere ridotti affinché la testa rientri comunque nel limite di ingombro protettivo della base, quindi la dimensione più lunga fornita può essere inferiore a quella richiesta. Il valore applicato non viene attualmente restituito nell'oggetto attività — se hai bisogno di confermare la dimensione effettivamente ricevuta, misura la bounding box della mesh keycap-head nel modello scaricato.

Offset verticale applicato alla testa prima che venga posizionata sulla base, in millimetri. Intervallo: [-5, 5].

La richiesta non era accettabile. Cause comuni:

• Parametro mancante: input_task_id e candidate_id sono obbligatori.
• UUID non valido: input_task_id non è un UUID valido.
• Attività padre non riuscita: l'attività di prototipo referenziata non ha ancora raggiunto lo stato SUCCEEDED.
• Nessun candidato: l'attività di prototipo è riuscita ma non ha prodotto candidati.
• Candidato sconosciuto: candidate_id non corrisponde a nessuno dei candidati dell'attività di input.
• Opzioni fuori intervallo: uno dei campi di options non rientrava nell'intervallo consentito o nell'insieme di valori enum.

Autenticazione non riuscita. Controlla la tua chiave API.

L'account è su un piano gratuito (è richiesto un piano a pagamento per creare attività) oppure ha crediti insufficienti.

L'attività di prototipo referenziata non esiste, appartiene a un altro utente oppure è stata creata tramite la webapp (solo le attività di prototipo in modalità API possono essere incatenate a una build).

Hai superato il tuo limite di frequenza.

Si è verificato un errore imprevisto lato server — ad esempio il servizio di moderation dei contenuti non era disponibile, il caricamento dell'immagine di input non è riuscito, oppure non è stato possibile creare l'attività. In questo caso non viene creata alcuna attività, quindi è sicuro riprovare.

Identificatore univoco dell'attività keycap da recuperare.

Identificatore univoco dell'attività keycap da annullare.

L'attività si trova già in uno stato terminale e non può essere annullata.

L'attività non esiste, appartiene a un altro utente, oppure la sua fase non corrisponde al percorso dell'URL.

Si è verificato un errore imprevisto lato server durante l'annullamento. L'attività potrebbe essere stata annullata oppure no: rileggila per confermare prima di riprovare.

Identificatore univoco dell'attività keycap da trasmettere in streaming.

prototype o build. La raccolta restituisce solo le attività la cui fase corrisponde all'URL — richiamare /prototype non restituisce mai attività di build e viceversa.

Numero di pagina per la paginazione.

Limite della dimensione della pagina. Il massimo consentito è 100 elementi.

Campo per cui ordinare. Valori disponibili:

• +created_at: Ordina per data di creazione in ordine crescente.
• -created_at: Ordina per data di creazione in ordine decrescente.

Identificatore univoco per il task. Sebbene utilizziamo un UUID k-sortable per gli id dei task come dettaglio implementativo, non dovresti fare alcuna assunzione sul formato dell'id.

Tipo del task. Il valore è creative-lab-keycap-prototype.

Il nome del task fornito al momento della creazione. Stringa vuota se non è stato fornito alcun nome.

Stato del task. I valori possibili sono uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progresso del task. Se il task non è ancora iniziato, questa proprietà sarà 0. Una volta che il task ha avuto successo, diventerà 100.

Timestamp di quando il task è stato creato, in millisecondi.

Timestamp di quando il task è stato avviato, in millisecondi. Se il task non è ancora iniziato, questa proprietà sarà 0.

Timestamp di quando il task è stato completato, in millisecondi. Se il task non è ancora terminato, questa proprietà sarà 0.

Timestamp di quando il risultato del task scade, in millisecondi.

Il conteggio dei task precedenti.

Dettagli dell'errore per i task falliti. Vedi Errori per il riferimento completo dell'oggetto task_error.

Il numero di crediti consumati da questo task. Un task che raggiunge SUCCEEDED viene addebitato per l'importo completo relativo alla sua fase. Un task che non viene mai creato (un 4xx al momento della richiesta, inclusa una rifiuto da moderation) non viene addebitato affatto. Un task che raggiunge FAILED restituisce 0 — l'addebito viene rimborsato, incluso un blocco di moderation asincrono. Annullare tramite DELETE rimborsa solo mentre il task è ancora PENDING; un task già IN_PROGRESS rimane addebitato, poiché il lavoro è già stato speso.

URL scaricabile del render del design del keycap finito — come appare il candidato come keycap finito. Contiene una singola voce; image_urls[i] corrisponde a candidate_ids[i]. Vuoto finché il task non raggiunge SUCCEEDED. L'URL è solo per la visualizzazione; l'endpoint di build consuma candidate_ids, non questi URL. Stesso ciclo di vita dell'URL di model_urls: firmato, senza header Authorization, valido fino a expires_at, e stabile quando il task viene riletto.

Identificatori di candidati opachi, paralleli a image_urls. Passa la voce corrispondente al design scelto come candidate_id della richiesta di build. Non fare alcuna assunzione sul formato di questi id.

Identificatore univoco per il task.

Tipo del task. Il valore è creative-lab-keycap-build.

Il nome del task fornito al momento della creazione. Stringa vuota se non è stato fornito alcun nome.

Stato del task. I valori possibili sono uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progress del task. Se il task non è ancora iniziato, questa proprietà sarà 0. Una volta che il task ha avuto successo, diventerà 100.

Timestamp di quando il task è stato creato, in millisecondi.

Timestamp di quando il task è stato avviato, in millisecondi.

Timestamp di quando il task è stato completato, in millisecondi.

Timestamp di quando il risultato del task scade, in millisecondi.

Il conteggio dei task precedenti. Significativo solo quando lo status è PENDING.

Dettagli dell'errore per i task falliti. Vedi Errori per il riferimento completo dell'oggetto task_error.

Il numero di crediti consumati da questo task. Un task che raggiunge lo stato SUCCEEDED viene addebitato per l'importo completo relativo alla sua fase. Un task che non viene mai creato (un 4xx al momento della richiesta, incluso un rifiuto di moderation) non viene addebitato affatto. Un task che raggiunge FAILED restituisce 0 — l'addebito viene rimborsato, incluso un blocco di moderation asincrono. L'annullamento tramite DELETE rimborsa solo mentre il task è ancora PENDING; un task già IN_PROGRESS rimane addebitato, poiché il lavoro è già stato svolto.

URL scaricabili per gli artefatti del modello generato. Sia il bundle GLB che quello OBJ vengono esportati in scala millimetrica reale, Y-up, con la parte anteriore del keycap rivolta verso +Z. Le mesh sono denominate keycap-head e keycap-base; quando la base ricade su un riempimento a pattern, è presente anche una terza mesh keycap-base-interior per la cavità dello stem. Non dare per scontato che vi siano esattamente due mesh.

Questi sono URL firmati: recuperali senza un header Authorization. Rimangono validi fino a expires_at, che è 3 giorni dopo finished_at, e rileggere il task all'interno di questa finestra temporale restituisce lo stesso URL identico anziché uno appena firmato. Scarica e archivia tu stesso i file prima di allora — non c'è modo di aggiornare un link scaduto.

URL scaricabili per le immagini di processo intermedie, indicizzate per tipo. Stesso ciclo di vita degli URL di model_urls: firmati, senza header Authorization, validi fino a expires_at, e stabili quando il task viene riletto. Tipi attualmente emessi:

• head_design — l'immagine di design del candidato scelto consumata dal build (sempre presente).
• composite — il render di visualizzazione del keycap finito relativo al candidato scelto (presente quando disponibile).
• base_canvas — il canvas dipinto della base del keycap (presente quando disponibile).

Considera l'insieme delle chiavi come aperto a estensioni; nuovi tipi potrebbero essere aggiunti senza che ciò costituisca una modifica incompatibile.