Creative Lab — Keycap API

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

O formato é detetado ao decodificar os dados da imagem, não a partir da extensão do ficheiro no URL — um URL sem extensão, ou um que redireciona, funciona desde que os bytes sejam decodificados para um formato suportado. Redirecionamentos HTTP são seguidos. A orientação EXIF é normalizada, portanto, uma foto de telemóvel rodada é usada da forma como aparece.

Limites: pelo menos 32 pixels de cada lado, no máximo 178,956,970 pixels no total, e no máximo 20,000,000 bytes uma vez descarregados. Para um Data URI, o limite aplica-se aos bytes decodificados, portanto, o ficheiro de origem pode ter até esse tamanho — é o texto base64 que é cerca de um terço maior, o que importa 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 maneiras de fornecer a imagem:

• URL publicamente acessível: Um URL acessível a partir da internet pública.
• Data URI: Um Data URI codificado em base64 da imagem. Exemplo de um Data URI: data:image/jpeg;base64,<your base64-encoded image data>.

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

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

Isto aplica-se apenas à renderização de exibição. O candidato que o endpoint de construção consome não é afetado, portanto, o resultado 3D é idêntico de qualquer maneira.

O pedido foi inaceitável. Causas comuns:

• Parâmetro em falta: image_url é obrigatório.
• Formato de imagem inválido: O image_url fornecido não é um formato suportado (.jpg, .jpeg, .png, .webp).
• Dimensões da imagem fora do intervalo: A imagem é muito pequena, excede o tamanho máximo do ficheiro ou excede o número máximo de pixels.
• URL inacessível: O image_url não pôde ser descarregado (404 ou timeout).
• Data URI inválido: A string base64 está malformada.
• Conteúdo sinalizado: A imagem de entrada foi sinalizada pela moderação NSFW.

A autenticação falhou. Por favor, 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 de entrada foi sinalizada pela moderação de propriedade intelectual.

Excedeu o seu limite de taxa.

Ocorreu um erro inesperado do lado do servidor — por exemplo, o serviço de moderação de conteúdo estava indisponível, a preparação da imagem de entrada falhou, ou a tarefa não pôde ser criada. Nenhuma tarefa é criada neste caso, portanto, tentar novamente é seguro.

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

Tarefas de protótipo criadas através da aplicação web 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 fonte 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 exibição. Máximo de 100 caracteres.

A base do keycap a ser construída. Atualmente, o único valor disponível é cherry-mx-1x1-r1 — um keycap padrão de perfil Cherry MX 1u. Estão planeados 3–5 tamanhos padrão adicionais; 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 ainda caiba no limite de proteção da base, portanto, a dimensão mais longa entregue pode ser menor do que a solicitada. O valor aplicado não é refletido de volta no objeto da tarefa hoje — se precisar confirmar o tamanho que realmente recebeu, meça a caixa delimitadora da malha keycap-head no modelo baixado.

Deslocamento vertical aplicado à cabeça antes de ser assentada 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.
• Pai não bem-sucedido: 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 options caiu fora do intervalo permitido ou conjunto de enumeração.

A autenticação falhou. Por favor, 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 um utilizador diferente, ou foi criada através da aplicação web (apenas tarefas de protótipo em modo API encadeiam em construção).

Excedeu o seu limite de taxa.

Ocorreu um erro inesperado no lado do servidor — por exemplo, o serviço de moderação de conteúdo estava indisponível, a preparação da imagem de entrada falhou, ou a tarefa não pôde ser criada. Nenhuma tarefa é criada neste caso, portanto, tentar novamente é seguro.

Identificador único para a tarefa de keycap a recuperar.

Identificador único para a tarefa de keycap a cancelar.

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

A tarefa não existe, pertence a um utilizador diferente, ou a sua fase não corresponde ao caminho do URL.

Ocorreu um erro inesperado do lado do servidor ao cancelar. A tarefa pode ou não ter sido cancelada — releia-a para confirmar antes de tentar novamente.

Identificador único para a tarefa de keycap a transmitir.

Ou prototype ou build. A coleção retorna apenas tarefas cujo estágio corresponde à URL — buscar /prototype nunca retorna tarefas de construção e vice-versa.

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

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

Campo para ordenar. Valores disponíveis:

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

Identificador único para a tarefa. Embora usemos um UUID ordenável por k para ids de tarefa 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 quando a tarefa foi criada. String vazia se nenhum nome foi fornecido.

Status 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 foi iniciada, esta propriedade será 0. Uma vez que a tarefa tenha sido concluída com sucesso, isto se tornará 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 foi iniciada, esta propriedade será 0.

Carimbo de data/hora de quando a tarefa foi concluída, em milissegundos. Se a tarefa ainda não foi 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 do erro para tarefas falhadas. Veja 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 pelo valor total da sua fase. Uma tarefa que nunca é criada (um 4xx no momento do pedido, incluindo uma rejeição de moderação) não é cobrada de todo. Uma tarefa que atinge FAILED retorna 0 — o valor é reembolsado, incluindo um bloqueio de moderação assíncrono. Cancelar via DELETE reembolsa apenas enquanto a tarefa ainda está PENDING; uma tarefa já IN_PROGRESS permanece cobrada, porque o trabalho foi gasto.

URL descarregável do render do design de keycap finalizado — como o candidato se parece como um keycap finalizado. Contém uma única entrada; image_urls[i] corresponde a candidate_ids[i]. Vazio até que a tarefa atinja SUCCEEDED. O URL é apenas para exibição; o endpoint de construção consome candidate_ids, não estes URLs. Mesmo ciclo de vida do URL que model_urls: assinado, sem cabeçalho Authorization, válido até expires_at, e estável quando a tarefa é relida.

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

Identificador único para a tarefa.

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

O nome da tarefa fornecido quando a tarefa foi criada. String vazia se nenhum nome foi fornecido.

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 foi iniciada, esta propriedade será 0. Uma vez que a tarefa tenha sido concluída com sucesso, isto se tornará 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.

Carimbo de data/hora de quando a tarefa foi concluída, em milissegundos.

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

A contagem de tarefas precedentes. Significativo apenas quando o estado é PENDING.

Detalhes do erro para tarefas falhadas. Veja 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 pelo valor total da sua fase. Uma tarefa que nunca é criada (um 4xx no momento da solicitação, incluindo uma rejeição de moderação) não é cobrada de todo. Uma tarefa que atinge FAILED retorna 0 — a cobrança é reembolsada, incluindo um bloqueio de moderação assíncrono. Cancelar via DELETE reembolsa apenas enquanto a tarefa ainda está PENDING; uma tarefa já IN_PROGRESS permanece cobrada, porque o trabalho já foi gasto.

URLs para download dos artefatos do modelo gerado. Tanto o pacote GLB quanto o OBJ são exportados em escala milimétrica do mundo real, Y-up, com a frente da keycap voltada para +Z. As malhas são nomeadas keycap-head e keycap-base; quando a base recorre a um preenchimento padrão, uma terceira malha keycap-base-interior também está presente para a cavidade do caule. Não assuma exatamente duas malhas.

Estas são URLs assinadas: obtenha-as sem um cabeçalho Authorization. Elas permanecem válidas até expires_at, que é 3 dias após finished_at, e reler a tarefa dentro desse período retorna o URL idêntico em vez de um novo assinado. Faça o download e armazene os arquivos você mesmo antes disso — não há como atualizar um link expirado.

URLs para download de imagens de processo intermediárias, indexadas por tipo. Mesmo ciclo de vida de URL que model_urls: assinadas, sem cabeçalho Authorization, válidas até expires_at, e estáveis quando a tarefa é relida. Tipos atualmente emitidos:

• head_design — a imagem de design do candidato escolhido que a construção consumiu (sempre presente).
• composite — a renderização de exibição da keycap finalizada do candidato escolhido (presente quando disponível).
• base_canvas — a tela da base da keycap pintada (presente quando disponível).

Trate o conjunto de chaves como aberto; novos tipos podem ser adicionados sem uma alteração de quebra.