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 é detectado decodificando os dados da imagem, não pela extensão do arquivo da URL — uma URL sem extensão, ou que redireciona, funciona desde que os bytes sejam decodificados para um formato suportado. Redirecionamentos HTTP são seguidos. A orientação EXIF é normalizada, então uma foto de telefone rotacionada é usada da forma como parece.

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 baixado. Para um Data URI, o limite se aplica aos bytes decodificados, então o arquivo de origem em si pode ter até esse tamanho — é o texto base64 que é cerca de um terço maior, o que importa para o corpo da sua solicitação, 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: Uma URL acessível da internet pública.
• Data URI: Um Data URI codificado em base64 da imagem. Exemplo de um Data URI: data:image/jpeg;base64,<seus dados de imagem codificados em base64>.

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

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

Isso se aplica apenas ao render de exibição. O candidato que o endpoint de construção consome não é afetado, então o resultado 3D é idêntico de qualquer forma.

A solicitação foi inaceitável. Causas comuns:

• Parâmetro ausente: 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 arquivo ou excede a contagem máxima de pixels.
• URL inacessível: O image_url não pôde ser baixado (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 sua chave de API.

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

A imagem de entrada foi sinalizada pela moderação de propriedade intelectual.

Você excedeu seu limite de taxa.

Ocorreu um erro inesperado no 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, então 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 do webapp não são aceitas — 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 ser construído, 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 planejados 3–5 tamanhos padrão adicionais; tamanhos personalizados não são suportados.

Tamanho alvo da cabeça esculpida, em milímetros: sua maior dimensão é 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, então a maior dimensão entregue pode ser menor do que a solicitada. O valor aplicado não é refletido de volta no objeto da tarefa hoje — se você 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].

A solicitação foi inaceitável. Causas comuns:

• Parâmetro ausente: 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 alcançou 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 sua chave de API.

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

A tarefa de protótipo referenciada não existe, pertence a um usuário diferente ou foi criada através do webapp (apenas tarefas de protótipo em modo API encadeiam em construção).

Você excedeu 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, então tentar novamente é seguro.

Identificador único para a tarefa de keycap a ser recuperada.

Identificador único para a tarefa de keycap a ser cancelada.

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

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

Ocorreu um erro inesperado no servidor ao cancelar. A tarefa pode ou não ter sido cancelada — leia novamente para confirmar antes de tentar novamente.

Identificador único para a tarefa de keycap a ser transmitida.

Ou prototype ou build. A coleção retorna apenas tarefas cujo estágio corresponda à URL — buscar /prototype nunca retorna tarefas de construçã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 para ordenar. Valores disponíveis:

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

Identificador único para a tarefa. Embora usemos um UUID ordenável por k para ids de tarefa como detalhe de implementação, você não deve fazer 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, isso 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 de 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 de sua etapa. Uma tarefa que nunca é criada (um 4xx no momento da solicitação, incluindo uma rejeição de moderação) não é cobrada. 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, pois o trabalho já foi realizado.

URL para download 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. A URL é apenas para exibição; o endpoint de construção consome candidate_ids, não essas URLs. Mesmo ciclo de vida da URL que model_urls: assinada, sem cabeçalho Authorization, válida 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 da solicitação de construção. Não faça suposições sobre o formato desses 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.

Status da tarefa. Os valores possíveis são um dos 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, isso 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 status é 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 de sua etapa. Uma tarefa que nunca é criada (um 4xx no momento da solicitação, incluindo uma rejeição de moderação) não é cobrada. 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, pois o trabalho já foi gasto.

URLs para download dos artefatos do modelo gerado. Tanto o GLB quanto o pacote OBJ são exportados em escala real em milímetros, Y para cima, com a frente do keycap voltada para +Z. As malhas são nomeadas keycap-head e keycap-base; quando a base recai para 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: busque-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 a URL idêntica em vez de uma recém-assinada. Baixe 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 do keycap finalizado do candidato escolhido (presente quando disponível).
• base_canvas — a tela da base do keycap pintada (presente quando disponível).

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