Creative Lab — Keycap API

Foto sorgente per Meshy da trasformare in immagini di design del keycap. Attualmente supportiamo i formati .jpg, .jpeg, .png e .webp.

Il formato è rilevato decodificando i dati dell'immagine, non dall'estensione del file dell'URL — un URL senza estensione, o uno che reindirizza, funziona finché i byte decodificano in un formato supportato. I reindirizzamenti HTTP sono seguiti. L'orientamento EXIF è normalizzato, quindi una foto ruotata del telefono viene utilizzata come appare.

Limiti: almeno 32 pixel su ciascun lato, al massimo 178,956,970 pixel in totale e al massimo 20,000,000 byte una volta scaricati. Per un Data URI il limite si applica ai byte decodificati, quindi il file sorgente stesso può essere fino a quella dimensione — è il testo base64 che è circa un terzo più grande, il che conta per il corpo della tua richiesta, non per questo limite. Un Data URI deve dichiarare un tipo di contenuto image/* e ;base64.

Ci sono due modi per fornire l'immagine:

• URL accessibile pubblicamente: Un URL accessibile da internet pubblica.
• Data URI: Un Data URI codificato in base64 dell'immagine. Esempio di un Data URI: data:image/jpeg;base64,<your base64-encoded image data>.

Nome dell'attività opzionale per scopi 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, così puoi comporlo su qualsiasi sfondo.

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

La richiesta non era accettabile. Cause comuni:

• Parametro mancante: image_url è richiesto.
• Formato immagine non valido: L'image_url fornito non è un formato supportato (.jpg, .jpeg, .png, .webp).
• Dimensioni immagine fuori intervallo: L'immagine è troppo piccola, supera la dimensione massima del file o supera il conteggio massimo dei pixel.
• URL irraggiungibile: L'image_url non può essere scaricato (404 o timeout).
• Data URI non valido: La stringa base64 è malformata.
• Contenuto segnalato: L'immagine di input è stata segnalata dalla moderation NSFW.

Autenticazione fallita. Si prega di controllare la tua chiave API.

L'account è sul piano gratuito (è richiesto un piano a pagamento per creare attività) o non ha crediti sufficienti.

L'immagine di input è stata segnalata dalla moderation della proprietà intellettuale.

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, la messa in scena dell'immagine di input è fallita, o l'attività non può essere creata. In questo caso non viene creata alcuna attività, quindi riprovare è sicuro.

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

I task di prototipo creati tramite l'app web non sono accettati — l'endpoint di costruzione accetta solo task di prototipo prodotti da POST /openapi/creative-lab/keycap/v1/prototype e rifiuta qualsiasi altra fonte con 404.

Il candidato da costruire, preso dall'array candidate_ids del task di prototipo riuscito. Deve appartenere a quel task; qualsiasi altro valore viene rifiutato con 400.

Nome del task opzionale 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 Cherry MX profilo 1u. Sono pianificate 3–5 dimensioni standard principali aggiuntive; le dimensioni personalizzate non sono supportate.

Dimensione target della testa scolpita, in millimetri: la sua dimensione più lunga è scalata a questo valore. Intervallo: [10, 40]. I valori superiori a circa 32.9 possono essere ridotti in modo che la testa rientri ancora nel limite dell'impronta protettiva della base, quindi la dimensione più lunga consegnata può essere inferiore a quella richiesta. Il valore applicato non viene restituito oggi sull'oggetto del task — se hai bisogno di confermare la dimensione effettivamente ricevuta, misura il 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 richiesti.
• UUID non valido: L'input_task_id non è un UUID valido.
• Genitore non riuscito: Il task di prototipo di riferimento non ha ancora raggiunto SUCCEEDED.
• Nessun candidato: Il task di prototipo è riuscito ma non ha prodotto candidati.
• Candidato sconosciuto: candidate_id non è uno dei candidati del task di input.
• Opzioni fuori intervallo: Uno dei campi options è caduto al di fuori del suo intervallo consentito o set di enumerazione.

Autenticazione fallita. Si prega di controllare la tua chiave API.

L'account è sul piano gratuito (è richiesto un piano a pagamento per creare task) o ha crediti insufficienti.

Il task di prototipo di riferimento non esiste, appartiene a un altro utente, o è stato creato tramite l'app web (solo i task di prototipo in modalità API si concatenano nella costruzione).

Hai superato il tuo limite di frequenza.

Si è verificato un errore inaspettato lato server — ad esempio il servizio di moderazione dei contenuti non era disponibile, la messa in scena dell'immagine di input è fallita, o il task non poteva essere creato. Nessun task viene creato in questo caso, quindi riprovare è sicuro.

Identificatore univoco per il task keycap da recuperare.

Identificatore univoco per l'attività keycap da annullare.

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

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

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

Identificatore univoco per il task keycap da trasmettere.

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

Numero di pagina per la paginazione.

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

Campo per l'ordinamento. Valori disponibili:

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

Identificatore univoco per il task. Anche se utilizziamo un UUID ordinabile per k per gli id dei task come dettaglio di implementazione, non dovresti fare alcuna assunzione sul formato dell'id.

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

Il nome del task fornito quando il task è stato creato. Stringa vuota se non è stato fornito alcun nome.

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

Avanzamento del task. Se il task non è ancora iniziato, questa proprietà sarà 0. Una volta che il task è riuscito, questo 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 completato, 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 all'oggetto task_error.

Il numero di crediti consumati da questo task. Un task che raggiunge SUCCEEDED viene addebitato l'intero importo per la sua fase. Un task che non viene mai creato (un 4xx al momento della richiesta, inclusa una moderazione rifiutata) non viene addebitato affatto. Un task che raggiunge FAILED restituisce 0 — l'addebito viene rimborsato, inclusa una moderazione asincrona bloccata. La cancellazione tramite DELETE rimborsa solo mentre il task è ancora PENDING; un task già IN_PROGRESS rimane addebitato, perché il lavoro è stato speso.

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

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

Identificatore univoco per il task.

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

Il nome del task fornito quando il task è stato creato. Stringa vuota se non è stato fornito alcun nome.

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

Avanzamento del task. Se il task non è ancora iniziato, questa proprietà sarà 0. Una volta che il task è riuscito, questo 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 stato è PENDING.

Dettagli degli errori per i task falliti. Vedi Errori per il riferimento completo all'oggetto task_error.

Il numero di crediti consumati da questo task. Un task che raggiunge SUCCEEDED viene addebitato l'intero importo per la sua fase. Un task che non viene mai creato (un 4xx al momento della richiesta, inclusa una moderazione rifiutata) non viene addebitato affatto. Un task che raggiunge FAILED restituisce 0 — l'addebito viene rimborsato, inclusa una moderazione asincrona bloccata. La cancellazione tramite DELETE rimborsa solo mentre il task è ancora PENDING; un task già IN_PROGRESS rimane addebitato, perché il lavoro è stato speso.

URL scaricabili per gli artefatti del modello generato. Sia il pacchetto GLB che quello OBJ sono esportati a scala millimetrica reale, Y-up, con la parte anteriore del keycap rivolta verso +Z. I mesh sono denominati keycap-head e keycap-base; quando la base ricade su un riempimento a motivo, è presente anche un terzo mesh keycap-base-interior per la cavità dello stelo. Non assumere esattamente due mesh.

Questi sono URL firmati: recuperali senza un'intestazione Authorization. Rimangono validi fino a expires_at, che è 3 giorni dopo finished_at, e rileggendo il task all'interno di quella finestra restituisce l'URL identico piuttosto che uno appena firmato. Scarica e archivia 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 come model_urls: firmati, nessuna intestazione Authorization, validi fino a expires_at, e stabili quando il task viene riletto. Tipi attualmente emessi:

• head_design — l'immagine del design del candidato scelto che la costruzione ha consumato (sempre presente).
• composite — il render di visualizzazione del keycap finito del candidato scelto (presente quando disponibile).
• base_canvas — la tela della base del keycap dipinta (presente quando disponibile).

Tratta il set di chiavi come aperto; nuovi tipi possono essere aggiunti senza una modifica di rottura.