API de Keycap do Creative Lab

A foto a ser transformada em um design de keycap, como uma URL pública ou um data URI (data:image/jpeg;base64,<seus dados de imagem codificados em base64>).

A imagem deve ser um arquivo JPG, JPEG, PNG ou WebP de no máximo 20 MB (20.000.000 bytes). Cada lado deve ter pelo menos 32 pixels, e a imagem pode ter no máximo 178.956.970 pixels no total. Uma imagem fora desses limites retorna 400.

A Meshy detecta o formato a partir dos dados da imagem, não da extensão do arquivo na URL. Uma URL sem extensão funciona, e a Meshy segue redirecionamentos HTTP. A Meshy aplica a orientação EXIF, para que uma foto de celular rotacionada saia da forma como aparece.

Um data URI deve ser codificado em base64 com um tipo de imagem, como data:image/png;base64,..., e a imagem decodificada deve ser JPEG, PNG ou WebP. O limite de 20 MB se aplica à imagem decodificada, então o texto em base64 pode ser cerca de um terço maior.

Um nome para a tarefa, com até 100 caracteres. Ele retorna no campo name da tarefa. Um nome mais longo retorna 400.

Se o fundo deve ser removido da imagem do protótipo. true retorna um PNG RGBA transparente, para que você possa colocar o keycap em qualquer fundo. Se a Meshy não conseguir remover o fundo, ela retorna a imagem com seu fundo, e a tarefa ainda é bem-sucedida.

O design da cabeça que o build transforma em 3D mantém seu fundo de qualquer forma. O build pinta a base do keycap a partir da imagem em image_urls, sem seu fundo se você enviou true. O build retorna essa imagem como process_image_urls.composite.

A requisição não pode ser executada. Por exemplo:

• image_url está ausente.
• A imagem não é um arquivo JPG, JPEG, PNG ou WebP.
• A imagem é muito pequena, tem mais de 20 MB, ou excede a contagem máxima de pixels.
• A Meshy não consegue baixar a imagem, por exemplo porque a URL retorna 404 ou expira o tempo limite.
• O data URI não é um base64 válido.
• A imagem foi sinalizada como NSFW.

A mensagem de erro informa qual problema foi encontrado. Corrija a requisição e envie-a novamente.

A chave de API está ausente ou é inválida. Verifique o cabeçalho Authorization.

Um destes se aplica:

• A conta não tem créditos suficientes.
• A chave de API, o espaço de trabalho ou o membro atingiu seu limite de créditos.
• A conta está no plano gratuito.

Verifique seus créditos e plano, depois tente novamente.

Sua equipe tem a opção IP Filtering ativada, e a Meshy sinalizou a imagem por propriedade intelectual de terceiros. Envie uma imagem que você tenha o direito de usar.

Um destes limites foi atingido:

• Você enviou mais requisições do que seu limite de taxa permite. Aguarde alguns segundos e tente novamente. Veja Limites de taxa.
• Muitas das suas tarefas estão na fila ou em execução. Aguarde algumas terminarem e tente novamente.
• Em um plano ilimitado sem créditos restantes, você atingiu o número de tarefas que podem ser executadas sem créditos. Aguarde uma tarefa terminar, ou adicione créditos.

A Meshy encontrou um erro de servidor, por exemplo porque a moderação de conteúdo ou a verificação de propriedade intelectual não puderam ser executadas, ou a Meshy não conseguiu armazenar a imagem. A Meshy não cria a tarefa, e reembolsa quaisquer créditos cobrados. Tente a requisição novamente.

O ID da tarefa de protótipo a ser construída. Deve ser uma tarefa criada pela sua conta com POST /openapi/creative-lab/keycap/v1/prototype, com o status SUCCEEDED.

Um ID que não corresponda a uma das suas tarefas de protótipo de Keycap da API retorna 404, incluindo um protótipo criado no aplicativo web.

O candidato a ser construído, do array candidate_ids da tarefa de protótipo. Um valor que não esteja nesse array retorna 400.

Um nome para a tarefa, com até 100 caracteres. Ele é retornado no campo name da tarefa. Um nome mais longo retorna 400.

A base de keycap sobre a qual construir. O único valor é cherry-mx-1x1-r1, um keycap padrão de perfil Cherry MX 1u. Tamanhos personalizados não são suportados, e qualquer outro valor retorna 400.

O tamanho da cabeça ao longo de sua maior dimensão, em milímetros, de 10 a 40. O Meshy escala a cabeça para que sua maior dimensão corresponda a esse valor. Um valor fora do intervalo retorna 400.

Para um valor acima de aproximadamente 32.9, o Meshy pode reduzir o tamanho para que a cabeça se ajuste ao limite de área de proteção da base. A cabeça pode então sair menor do que o solicitado. O objeto da tarefa não retorna o tamanho que o Meshy aplicou. Para verificá-lo, meça a caixa delimitadora da malha keycap-head no modelo.

O deslocamento vertical a ser aplicado à cabeça antes que o Meshy a posicione na base, em milímetros, de -5 a 5. Um valor fora do intervalo retorna 400.

A solicitação não pode ser executada. Por exemplo:

• input_task_id está ausente ou não é um ID de tarefa válido.
• O status da tarefa de protótipo não é SUCCEEDED. Se ainda estiver em execução, aguarde e tente novamente. Se tiver falhado ou sido cancelada, crie uma nova tarefa de protótipo.
• A tarefa de protótipo teve sucesso, mas não possui candidatos. Crie uma nova tarefa de protótipo.
• candidate_id está ausente ou não está em candidate_ids da tarefa de protótipo. Envie um valor desse array.
• Um campo em options está fora do intervalo, ou base_model não é um valor disponível.

A mensagem de erro indica qual problema foi encontrado.

A chave de API está ausente ou é inválida. Verifique o cabeçalho Authorization.

Uma das situações a seguir se aplica:

• A conta não tem créditos suficientes.
• A chave de API, o espaço de trabalho ou o membro atingiu seu limite de créditos.
• A conta está no plano gratuito.

Verifique seus créditos e plano e tente novamente.

input_task_id não corresponde a nenhuma tarefa de protótipo de Keycap criada pela sua conta via API. Um protótipo criado no aplicativo web também retorna 404. Envie o ID result de uma resposta de criação de protótipo.

Um dos seguintes limites foi atingido:

• Você enviou mais solicitações do que seu limite de taxa permite. Aguarde alguns segundos e tente novamente. Consulte Limites de taxa.
• Há muitas tarefas suas na fila ou em execução. Aguarde algumas terminarem e tente novamente.
• Em um plano ilimitado sem créditos restantes, você atingiu o número de tarefas que podem ser executadas sem créditos. Aguarde uma tarefa terminar ou adicione créditos.

O Meshy não conseguiu criar a tarefa devido a um erro de servidor. O Meshy reembolsa quaisquer créditos cobrados. Tente a solicitação novamente.

O ID da tarefa retornado na resposta de criação.

id não é um ID de tarefa válido. Envie o ID result retornado na resposta de criação.

Sua equipe está com a Filtragem de IP ativada, e a Meshy sinalizou a imagem da tarefa de protótipo por propriedade intelectual de terceiros. Tarefas de build e equipes no plano Enterprise não recebem esse erro. Crie uma tarefa de protótipo a partir de uma imagem sobre a qual você tenha os direitos de uso.

Nenhuma tarefa de Keycap com esse ID pertence à sua conta, ou o estágio da tarefa não corresponde ao caminho. Verifique o ID e use /prototype ou /build de acordo com a tarefa.

A Meshy não conseguiu executar a verificação de propriedade intelectual. Repita a solicitação.

O ID da tarefa a ser cancelada.

Um dos seguintes se aplica:

• id não é um ID de tarefa válido. Envie o ID result da resposta de criação.
• A tarefa já tem um status final (SUCCEEDED, FAILED ou CANCELED), então não pode ser cancelada.

Nenhuma tarefa do Keycap com este ID pertence à sua conta, ou o estágio da tarefa não corresponde ao caminho. Verifique o ID e use /prototype ou /build para corresponder à tarefa.

O Meshy encontrou um erro de servidor ao cancelar a tarefa, então a tarefa pode ou não estar cancelada. Obtenha a tarefa para verificar seu status antes de tentar novamente.

O ID da tarefa a partir da resposta de criação.

O estágio a listar, prototype ou build.

A página a retornar, de 1 a 255. 0 retorna a primeira página. Um valor fora de 0 a 255 retorna 400.

Número de tarefas por página, até 100. Um valor de 101 a 255 retorna 100 tarefas, e 0 usa o padrão. Um valor fora de 0 a 255 retorna 400.

A ordem de classificação.

Valores disponíveis:

• -created_at: mais recentes primeiro
• +created_at: mais antigas primeiro

O ID da tarefa. Não dependa do seu formato.

O tipo da tarefa, sempre creative-lab-keycap-prototype.

O name que você enviou ao criar a tarefa, ou "" se você não enviou nenhum.

O status da tarefa.

Valores disponíveis:

• PENDING: aguardando na fila
• IN_PROGRESS: gerando o resultado
• SUCCEEDED: final, com o resultado
• FAILED: final, com o motivo em task_error
• CANCELED: final, sem resultado

Porcentagem do trabalho concluído, de 0 a 100. É 0 até a tarefa começar e 100 quando ela é bem-sucedida.

Horário em que a tarefa foi criada, em milissegundos Unix.

Horário em que um worker iniciou a tarefa, em milissegundos Unix. null até então.

Horário em que a tarefa atingiu um status final, em milissegundos Unix. null até então.

Horário em que o resultado da tarefa expira, em milissegundos Unix. É 3 dias após finished_at, ou 3 dias após created_at até a tarefa terminar. Para contas Enterprise, que mantêm os resultados da API indefinidamente, é cerca de 100 anos depois. Veja Retenção de recursos.

A posição da tarefa na fila enquanto está PENDING. 1 significa que ela começa em seguida. 0 depois que a tarefa sai da fila, e sempre 0 em resultados de listagem.

Por que a tarefa falhou. null a menos que status seja FAILED. Veja Erros.

Número de créditos cobrados pela tarefa, após qualquer reembolso. Uma requisição que retorna um erro não é cobrada. Uma tarefa que falha é 0, porque a Meshy a reembolsa. Cancelar reembolsa uma tarefa apenas enquanto ela está PENDING. Se a Meshy não conseguir ler a cobrança, uma resposta de get ou stream deixa o campo de fora, e uma requisição de listagem retorna 500. Nesse caso, tente a requisição novamente.

URLs de download para a imagem do keycap finalizado. O array tem uma URL depois que a tarefa é bem-sucedida, e fica vazio até então. image_urls[i] mostra o candidato em candidate_ids[i].

Essas URLs são para exibição. O endpoint de build recebe uma entrada de candidate_ids, não uma URL. São URLs assinadas, então busque-as sem um cabeçalho Authorization. Elas permanecem válidas até expires_at, e obter a tarefa novamente retorna as mesmas URLs.

IDs dos candidatos, na mesma ordem que image_urls. Para fazer o build de um candidato, envie seu ID como candidate_id na requisição de build. Não dependa do formato desses IDs.

O ID da tarefa. Não dependa do seu formato.

O tipo da tarefa, sempre creative-lab-keycap-build.

O name que você enviou ao criar a tarefa, ou "" se você não enviou nenhum.

O status da tarefa.

Valores disponíveis:

• PENDING: aguardando na fila
• IN_PROGRESS: gerando o resultado
• SUCCEEDED: final, com o resultado
• FAILED: final, com o motivo em task_error
• CANCELED: final, sem resultado

Porcentagem do trabalho concluído, de 0 a 100. É 0 até a tarefa iniciar e 100 quando ela é bem-sucedida.

Horário em que a tarefa foi criada, em milissegundos Unix.

Horário em que um worker iniciou a tarefa, em milissegundos Unix. null até então.

Horário em que a tarefa atingiu um status final, em milissegundos Unix. null até então.

Horário em que o resultado da tarefa expira, em milissegundos Unix. É 3 dias após finished_at, ou 3 dias após created_at até a tarefa terminar. Para contas Enterprise, que mantêm os resultados da API indefinidamente, é cerca de 100 anos depois. Consulte Retenção de recursos.

A posição da tarefa na fila enquanto ela está PENDING. 1 significa que ela começa em seguida. 0 depois que a tarefa sai da fila, e sempre 0 em resultados de listagem.

Motivo da falha da tarefa. null a menos que status seja FAILED. Consulte Erros.

Número de créditos cobrados pela tarefa, após qualquer reembolso. Uma solicitação que retorna um erro não é cobrada. Uma tarefa com falha é 0, pois a Meshy a reembolsa. Cancelar reembolsa uma tarefa apenas enquanto ela está PENDING. Se a Meshy não conseguir ler a cobrança, uma resposta de get ou stream deixa o campo de fora, e uma solicitação de listagem retorna 500. Nesse caso, tente novamente a solicitação.

URLs de download para o modelo 3D. A Meshy exporta o arquivo GLB e o pacote OBJ em escala real, em milímetros, com o eixo Y para cima e a frente do keycap voltada para +Z.

O modelo tem malhas chamadas keycap-head e keycap-base. Quando a Meshy recorre a um preenchimento de padrão para a base, o modelo também tem uma malha keycap-base-interior para a cavidade da haste. Não presuma que o modelo tem exatamente duas malhas.

Essas são URLs assinadas, então busque-as sem um cabeçalho Authorization. Elas permanecem válidas até expires_at, e obter a tarefa novamente antes disso retorna as mesmas URLs. Uma URL expirada não pode ser renovada, então baixe e armazene os arquivos antes disso.

URLs de download para imagens das etapas do build, organizadas por tipo. Assim como model_urls, são URLs assinadas, então busque-as sem um cabeçalho Authorization. Elas permanecem válidas até expires_at, e obter a tarefa novamente retorna as mesmas URLs.

Pode ter estas chaves:

• head_design: a imagem de design do candidato escolhido, que o build transformou em 3D. Sempre presente.
• composite: a imagem do keycap finalizado para o candidato escolhido, a partir da qual o build pintou a base. Pode estar ausente.
• base_canvas: a base pintada do keycap. Pode estar ausente.

A Meshy pode adicionar chaves, então ignore uma chave que você não reconheça.