Creative Lab — API de Keycap

Foto de origem para o Meshy transformar em imagens de design de keycap. Atualmente, suportamos os formatos .jpg, .jpeg, .png e .webp.

O formato é detetado através da descodificação dos dados da imagem, não a partir da extensão de ficheiro do URL — um URL sem extensão, ou que redirecione, funciona desde que os bytes sejam descodificados para um formato suportado. Os redirecionamentos HTTP são seguidos. A orientação EXIF é normalizada, pelo que uma foto de telemóvel rodada é utilizada tal como é apresentada visualmente.

Limites: pelo menos 32 pixels em cada lado, no máximo 178.956.970 pixels no total, e no máximo 20.000.000 bytes após a transferência. Para um Data URI, o limite aplica-se aos bytes descodificados, pelo que o ficheiro de origem em si pode ter até esse tamanho — é o texto base64 que fica cerca de um terço maior, o que é relevante para o corpo do seu pedido, não para este limite. Um Data URI deve declarar um tipo de conteúdo image/* e ;base64.

Existem duas formas de fornecer a imagem:

• URL publicamente acessível: Um URL que seja acessível a partir da internet pública.
• Data URI: Um Data URI da imagem codificado em base64. Exemplo de um Data URI: data:image/jpeg;base64,<os seus dados de imagem codificados em base64>.

Nome opcional da tarefa para fins de apresentação. Máximo de 100 carateres.

Quando definido como true, a renderização de exibição devolvida em image_urls é um PNG RGBA transparente com o fundo removido, para que possa compô-la sobre qualquer fundo.

Isto aplica-se apenas à renderização de exibição. O candidato consumido pelo endpoint de build não é afetado, pelo que o resultado 3D é idêntico em ambos os casos.

O pedido era inaceitável. Causas comuns:

• Parâmetro em falta: image_url é obrigatório.
• Formato de imagem inválido: O image_url fornecido não está num formato suportado (.jpg, .jpeg, .png, .webp).
• Dimensões da imagem fora do intervalo permitido: A imagem é demasiado pequena, excede o tamanho máximo de ficheiro ou excede o número máximo de pixels.
• URL inacessível: Não foi possível transferir o image_url (404 ou timeout).
• Data URI inválido: A cadeia base64 está mal formada.
• Conteúdo assinalado: A imagem fornecida foi assinalada pela moderation de conteúdo impróprio (NSFW).

A autenticação falhou. Verifique a sua chave de API.

A conta está no plano gratuito (é necessário um plano pago para criar tarefas) ou não tem créditos suficientes.

A imagem fornecida foi assinalada pela moderation de propriedade intelectual.

Excedeu o seu limite de taxa.

Ocorreu um erro inesperado do lado do servidor — por exemplo, o serviço de moderation de conteúdo estava indisponível, o carregamento da imagem de entrada falhou, ou não foi possível criar a tarefa. Neste caso, nenhuma tarefa é criada, pelo que é seguro tentar novamente.

O ID da tarefa de uma tarefa de protótipo criada através deste mesmo endpoint OpenAPI. O protótipo deve ter sido criado pela mesma conta Meshy, deve ter atingido SUCCEEDED e deve ter produzido pelo menos um candidato.

Tarefas de protótipo criadas através da webapp não são aceites — o endpoint de construção aceita apenas tarefas de protótipo produzidas por POST /openapi/creative-lab/keycap/v1/prototype e recusa qualquer outra origem com 404.

O candidato a construir, retirado do array candidate_ids da tarefa de protótipo bem-sucedida. Deve pertencer a essa tarefa; qualquer outro valor é rejeitado com 400.

Nome opcional da tarefa para fins de apresentação. Máximo de 100 caracteres.

A base de keycap sobre a qual construir. Atualmente, o único valor disponível é cherry-mx-1x1-r1 — uma keycap padrão de perfil Cherry MX 1u. Estão planeadas 3–5 dimensões padrão adicionais habituais; tamanhos personalizados não são suportados.

Tamanho alvo da cabeça esculpida, em milímetros: a sua dimensão mais longa é escalada para este valor. Intervalo: [10, 40]. Valores acima de aproximadamente 32.9 podem ser reduzidos para que a cabeça continue a caber no limite de área protegida da base, pelo que a dimensão mais longa entregue pode ser inferior à solicitada. O valor aplicado não é atualmente devolvido no objeto da tarefa — se precisar de confirmar o tamanho que realmente recebeu, meça a caixa delimitadora da malha keycap-head no modelo transferido.

Deslocamento vertical aplicado à cabeça antes de esta ser assente na base, em milímetros. Intervalo: [-5, 5].

O pedido foi inaceitável. Causas comuns:

• Parâmetro em falta: input_task_id e candidate_id são obrigatórios.
• UUID inválido: O input_task_id não é um UUID válido.
• Tarefa principal não concluída: A tarefa de protótipo referenciada ainda não atingiu SUCCEEDED.
• Sem candidatos: A tarefa de protótipo foi bem-sucedida, mas não produziu candidatos.
• Candidato desconhecido: candidate_id não é um dos candidatos da tarefa de entrada.
• Opções fora do intervalo: Um dos campos de options encontrava-se fora do intervalo permitido ou do conjunto de valores enumerados.

A autenticação falhou. Verifique a sua chave de API.

A conta está no plano gratuito (é necessário um plano pago para criar tarefas) ou não tem créditos suficientes.

A tarefa de protótipo referenciada não existe, pertence a outro utilizador, ou foi criada através da webapp (apenas tarefas de protótipo em modo API podem encadear-se numa construção).

Excedeu o seu limite de taxa.

Ocorreu um erro inesperado do lado do servidor — por exemplo, o serviço de moderation estava indisponível, falhou a preparação da imagem de entrada, ou não foi possível criar a tarefa. Neste caso, não é criada nenhuma tarefa, pelo que é seguro tentar novamente.

Identificador único da tarefa de keycap a obter.

Identificador único da tarefa de keycap a cancelar.

A tarefa já se encontra num estado terminal e não pode ser cancelada.

A tarefa não existe, pertence a um utilizador diferente, ou o seu estágio não corresponde ao caminho do URL.

Ocorreu um erro inesperado do lado do servidor durante o cancelamento. A tarefa pode ou não ter sido cancelada — volte a lê-la para confirmar antes de tentar novamente.

Identificador único da tarefa de keycap para fazer stream.

prototype ou build. A coleção devolve apenas tarefas cujo estágio corresponda ao URL — obter /prototype nunca devolve tarefas de compilação e vice-versa.

Número da página para paginação.

Limite de tamanho da página. O máximo permitido é 100 itens.

Campo pelo qual ordenar. Valores disponíveis:

• +created_at: Ordena por hora de criação em ordem ascendente.
• -created_at: Ordena por hora de criação em ordem descendente.

Identificador único da tarefa. Embora utilizemos um UUID k-sortable para os ids das tarefas como detalhe de implementação, não deve fazer quaisquer suposições sobre o formato do id.

Tipo da tarefa. O valor é creative-lab-keycap-prototype.

O nome da tarefa fornecido no momento da criação da tarefa. String vazia se não tiver sido fornecido nenhum nome.

Estado da tarefa. Os valores possíveis são um de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progress da tarefa. Se a tarefa ainda não tiver começado, esta propriedade será 0. Assim que a tarefa for concluída com sucesso, este valor passará a ser 100.

Carimbo de data/hora de quando a tarefa foi criada, em milissegundos.

Carimbo de data/hora de quando a tarefa foi iniciada, em milissegundos. Se a tarefa ainda não tiver sido iniciada, esta propriedade será 0.

Carimbo de data/hora de quando a tarefa foi concluída, em milissegundos. Se a tarefa ainda não tiver sido concluída, esta propriedade será 0.

Carimbo de data/hora de quando o resultado da tarefa expira, em milissegundos.

A contagem de tarefas precedentes.

Detalhes de erro para tarefas falhadas. Consulte Erros para a referência completa do objeto task_error.

O número de créditos consumidos por esta tarefa. Uma tarefa que atinge SUCCEEDED é cobrada na totalidade correspondente à sua etapa. Uma tarefa que nunca chega a ser criada (um 4xx no momento do pedido, incluindo uma rejeição por moderation) não é cobrada de todo. Uma tarefa que atinge FAILED devolve 0 — a cobrança é reembolsada, incluindo um bloqueio de moderation assíncrono. Cancelar através de DELETE só reembolsa enquanto a tarefa ainda estiver PENDING; uma tarefa já IN_PROGRESS mantém-se cobrada, porque o trabalho já foi despendido.

URL transferível da renderização do design de keycap finalizado — o aspeto que o candidato tem como keycap acabado. Contém uma única entrada; image_urls[i] corresponde a candidate_ids[i]. Vazio até a tarefa atingir SUCCEEDED. O URL destina-se apenas a exibição; o endpoint de construção consome candidate_ids, não estes URLs. O mesmo ciclo de vida de URL que model_urls: assinado, sem cabeçalho Authorization, válido até expires_at, e estável quando a tarefa é relida.

Identificadores opacos de candidatos, paralelos a image_urls. Passe a entrada correspondente ao design escolhido como o candidate_id do pedido de construção. Não faça quaisquer suposições sobre o formato destes ids.

Identificador único da tarefa.

Tipo da tarefa. O valor é creative-lab-keycap-build.

O nome da tarefa fornecido no momento da criação da tarefa. Cadeia vazia se não foi fornecido nenhum nome.

Estado da tarefa. Os valores possíveis são um de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progresso da tarefa. Se a tarefa ainda não tiver sido iniciada, esta propriedade será 0. Assim que a tarefa for bem-sucedida, este valor passará a ser 100.

Carimbo de data/hora da criação da tarefa, em milissegundos.

Carimbo de data/hora do início da tarefa, em milissegundos.

Carimbo de data/hora da conclusão da tarefa, em milissegundos.

Carimbo de data/hora de expiração do resultado da tarefa, em milissegundos.

O número de tarefas precedentes. Só é relevante quando o estado é PENDING.

Detalhes do erro para tarefas com falha. Consulte Erros para a referência completa do objeto task_error.

O número de créditos consumidos por esta tarefa. Uma tarefa que atinge SUCCEEDED é cobrada com o valor total correspondente à sua etapa. Uma tarefa que nunca chega a ser criada (um 4xx no momento do pedido, incluindo uma rejeição de moderation) não é cobrada de todo. Uma tarefa que atinge FAILED devolve 0 — o valor é reembolsado, incluindo um bloqueio de moderation assíncrono. O cancelamento via DELETE só reembolsa enquanto a tarefa ainda estiver PENDING; uma tarefa já IN_PROGRESS mantém-se cobrada, porque o trabalho já foi realizado.

URLs transferíveis para os artefactos do modelo gerado. Tanto o GLB como o pacote OBJ são exportados à escala real em milímetros, com o eixo Y para cima, com a frente do keycap virada para +Z. As malhas têm o nome keycap-head e keycap-base; quando a base recorre a um preenchimento em padrão, está também presente uma terceira malha keycap-base-interior para a cavidade da haste. Não presuma que existem exatamente duas malhas.

Estes são URLs assinados: obtenha-os sem um cabeçalho Authorization. Permanecem válidos até expires_at, que corresponde a 3 dias após finished_at, e reler a tarefa dentro desse período devolve o mesmo URL, e não um novo URL assinado. Transfira e guarde os ficheiros por si mesmo antes disso — não há forma de renovar uma ligação expirada.

URLs transferíveis para imagens intermédias do processo, organizadas por tipo. O mesmo ciclo de vida de URL que model_urls: assinados, sem cabeçalho Authorization, válidos até expires_at, e estáveis ao reler a tarefa. Tipos atualmente emitidos:

• head_design — a imagem de design do candidato escolhido que a build consumiu (sempre presente).
• composite — o render de apresentação do keycap finalizado do candidato escolhido (presente quando disponível).
• base_canvas — a tela pintada da base do keycap (presente quando disponível).

Considere o conjunto de chaves como aberto; podem ser adicionados novos tipos sem constituir uma alteração disruptiva.