Creative Lab — API de Keycap

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

O formato é detectado ao decodificar os dados da imagem, não pela extensão de arquivo da URL — uma URL sem extensão, ou uma que redireciona, funciona desde que os bytes sejam decodificados para um formato compatível. Redirecionamentos HTTP são seguidos. A orientação EXIF é normalizada, então uma foto de celular rotacionada é usada da forma como aparece visualmente.

Limites: no mínimo 32 pixels em cada lado, no máximo 178.956.970 pixels no total, e no máximo 20.000.000 bytes após o download. 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 em base64 que fica cerca de um terço maior, o que importa para o corpo da sua requisição, não para esse limite. Um Data URI deve declarar um content type image/* e ;base64.

Existem duas maneiras de fornecer a imagem:

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

Nome opcional da tarefa 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 você possa compor sobre qualquer fundo.

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

A requisição era inaceitável. Causas comuns:

• Parâmetro ausente: image_url é obrigatório.
• Formato de imagem inválido: O image_url fornecido não está em um formato suportado (.jpg, .jpeg, .png, .webp).
• Dimensões de imagem fora do intervalo: A imagem é muito pequena, excede o tamanho máximo de 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 em base64 está malformada.
• Conteúdo sinalizado: A imagem de entrada foi sinalizada pela moderation de NSFW.

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

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

A imagem de entrada foi sinalizada pela moderation de propriedade intelectual.

Você excedeu seu limite de taxa.

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

O ID da tarefa de um protótipo criado por meio deste mesmo endpoint da 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 por meio da webapp não são aceitas — o endpoint de build 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 ser construído, obtido a partir 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 de keycap sobre a qual construir. Atualmente, o único valor disponível é cherry-mx-1x1-r1 — um keycap padrão de perfil Cherry MX 1u. Estão planejados de 3 a 5 tamanhos padrão adicionais amplamente utilizados; tamanhos personalizados não são suportados.

Tamanho alvo da cabeça esculpida, em milímetros: sua maior dimensão é escalada para esse valor. Intervalo: [10, 40]. Valores acima de aproximadamente 32.9 podem ser reduzidos para que a cabeça ainda caiba dentro do limite de área de proteção da base, de modo que a maior dimensão entregue pode ser menor do que a solicitada. O valor aplicado não é retornado no objeto da tarefa atualmente — se você precisar confirmar o tamanho realmente obtido, meça a caixa delimitadora da malha keycap-head no modelo baixado.

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

A requisiçã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.
• Tarefa pai 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 nenhum candidato.
• Candidato desconhecido: candidate_id não é um dos candidatos da tarefa de entrada.
• Opções fora do intervalo: Um dos campos de options ficou fora do intervalo permitido ou do conjunto de valores enumerados.

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

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

A tarefa de protótipo referenciada não existe, pertence a outro usuário ou foi criada por meio da webapp (apenas tarefas de protótipo criadas em modo API se encadeiam para o build).

Você excedeu seu limite de taxa.

Ocorreu um erro inesperado do lado do servidor — por exemplo, o serviço de moderation estava indisponível, o estágio de preparação da imagem de entrada falhou, ou a tarefa não pôde ser criada. Nesse caso, nenhuma tarefa é criada, portanto tentar novamente é seguro.

Identificador único da tarefa de keycap a ser recuperada.

Identificador único da tarefa 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 sua etapa não corresponde ao caminho da URL.

Ocorreu um erro inesperado no servidor durante o cancelamento. A tarefa pode ou não ter sido cancelada — leia-a novamente para confirmar antes de tentar de novo.

Identificador único da tarefa de keycap a ser transmitida.

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

• +created_at: Ordena pelo horário de criação em ordem crescente.
• -created_at: Ordena pelo horário de criação em ordem decrescente.

Identificador único da tarefa. Embora usemos um UUID k-sortable para os 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 dos seguintes: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progress da tarefa. Se a tarefa ainda não foi iniciada, essa propriedade será 0. Assim que a tarefa for concluída com sucesso, ela 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, essa 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, essa 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 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 pelo valor integral referente à sua etapa. Uma tarefa que nunca chega a ser criada (um 4xx no momento da requisição, incluindo uma rejeição de moderation) não é cobrada de forma alguma. Uma tarefa que atinge FAILED retorna 0 — a cobrança é reembolsada, incluindo um bloqueio de moderation assíncrono. Cancelar por meio de DELETE reembolsa apenas enquanto a tarefa ainda estiver PENDING; uma tarefa já IN_PROGRESS permanece cobrada, pois o trabalho já foi realizado.

URL para download da renderização do design de keycap finalizado — a aparência do candidato 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 build consome candidate_ids, não essas URLs. Mesmo ciclo de vida de URL que model_urls: assinada, sem cabeçalho Authorization, válida 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 da requisição de build. 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 ela foi criada. Uma string vazia se nenhum nome foi fornecido.

Status 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 foi iniciada, essa propriedade será 0. Uma vez que a tarefa tenha sido concluída com sucesso, ela 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 finalizada, em milissegundos.

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

A contagem de tarefas precedentes. Relevante apenas quando o status é PENDING.

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

O número de créditos consumidos por essa tarefa. Uma tarefa que atinge SUCCEEDED é cobrada no valor total referente à sua etapa. Uma tarefa que nunca chega a ser criada (um 4xx no momento da requisição, incluindo uma rejeição de moderation) não é cobrada de forma alguma. Uma tarefa que atinge FAILED retorna 0 — a cobrança é reembolsada, incluindo em um bloqueio de moderation 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.

URLs para download dos artefatos do modelo gerado. Tanto o GLB quanto o pacote OBJ são exportados em escala de milímetros do mundo real, com Y para cima, com a frente do keycap voltada para +Z. As malhas são nomeadas keycap-head e keycap-base; quando a base recorre a um preenchimento de padrão (pattern fill), uma terceira malha keycap-base-interior também está presente para a cavidade do stem. Não assuma que existirão exatamente duas malhas.

Estas são URLs assinadas: busque-as sem um header 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. Faça o download e armazene os arquivos por conta própria antes disso — não há como renovar um link expirado.

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

• head_design — a imagem de design do candidato escolhido que a build consumiu (sempre presente).
• composite — a renderização de exibição do keycap finalizado do candidato escolhido (presente quando disponível).
• base_canvas — o canvas pintado da base do keycap (presente quando disponível).

Trate o conjunto de chaves como aberto a expansão; novos tipos podem ser adicionados sem que isso seja uma alteração que quebre a compatibilidade.