API de Keycap do Creative Lab

A fotografia a transformar num design de keycap, como um URL público ou um data URI (data:image/jpeg;base64,<your base64-encoded image data>).

A imagem deve ser um ficheiro JPG, JPEG, PNG ou WebP com, 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 destes limites devolve 400.

A Meshy deteta o formato a partir dos dados da imagem, não a partir da extensão do ficheiro no URL. Um URL sem extensão funciona, e a Meshy segue redirecionamentos HTTP. A Meshy aplica a orientação EXIF, pelo que uma fotografia de telemóvel rodada sai como aparece.

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

Um nome para a tarefa, com até 100 carateres. É devolvido no campo name da tarefa. Um nome mais longo devolve 400.

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

O design da cabeça que a construção transforma em 3D mantém o seu fundo em qualquer dos casos. A construção pinta a base do keycap a partir da imagem em image_urls, sem o seu fundo se tiver enviado true. A construção devolve essa imagem como process_image_urls.composite.

O pedido não pode ser executado. Por exemplo:

• image_url está em falta.
• A imagem não é um ficheiro JPG, JPEG, PNG ou WebP.
• A imagem é demasiado pequena, excede os 20 MB, ou excede o número máximo de pixels.
• A Meshy não consegue transferir a imagem, por exemplo porque o URL devolve 404 ou expira o tempo de espera.
• O data URI não é um base64 válido.
• A imagem foi assinalada como NSFW.

A mensagem de erro indica qual o problema encontrado. Corrija o pedido e envie-o novamente.

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

Aplica-se uma das seguintes situações:

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

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

A sua equipa tem a Filtragem de IP ativada, e a Meshy assinalou a imagem por propriedade intelectual de terceiros. Envie uma imagem que tenha o direito de utilizar.

Um destes limites foi atingido:

• Enviou mais pedidos do que o seu limite de taxa permite. Aguarde alguns segundos e tente novamente. Consulte Limites de taxa.
• Há demasiadas tarefas suas em fila de espera ou em execução. Aguarde que algumas terminem e tente novamente.
• Num plano ilimitado sem créditos restantes, atingiu o número de tarefas que podem ser executadas sem créditos. Aguarde que uma tarefa termine, 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 que tenha cobrado. Tente novamente o pedido.

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

Um ID que não corresponda a uma das suas tarefas de protótipo de Keycap criadas através da API devolve 404, incluindo um protótipo criado na aplicação web.

O candidato a construir, do array candidate_ids da tarefa de protótipo. Um valor que não esteja presente nesse array devolve 400.

Um nome para a tarefa, até 100 caracteres. É devolvido no campo name da tarefa. Um nome mais longo devolve 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 devolve 400.

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

Para um valor acima de aproximadamente 32.9, a Meshy pode reduzir o tamanho para que a cabeça se ajuste ao limite de ocupação protegida da base. A cabeça pode então sair mais pequena do que o pedido. O objeto da tarefa não devolve o tamanho aplicado pela Meshy. Para o verificar, meça a caixa delimitadora da malha keycap-head no modelo.

O deslocamento vertical a aplicar à cabeça antes de a Meshy a encaixar na base, em milímetros, de -5 a 5. Um valor fora do intervalo devolve 400.

O pedido não pode ser executado. Por exemplo:

• input_task_id está em falta ou não é um ID de tarefa válido.
• O estado 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 foi bem-sucedida, mas não tem candidatos. Crie uma nova tarefa de protótipo.
• candidate_id está em falta, ou não consta no 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 o problema encontrado.

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

Aplica-se uma das seguintes situações:

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

Verifique os seus créditos e o seu plano, e tente novamente.

input_task_id não corresponde a nenhuma tarefa de protótipo de Keycap criada pela sua conta através da API. Um protótipo criado na aplicação web também devolve 404. Envie o ID result de uma resposta de criação de protótipo.

Um destes limites foi atingido:

• Enviou mais pedidos do que o permitido pelo seu limite de taxa. Aguarde alguns segundos e tente novamente. Consulte Limites de taxa.
• Demasiadas das suas tarefas estão em fila de espera ou em execução. Aguarde que algumas terminem e tente novamente.
• Num plano ilimitado sem créditos disponíveis, atingiu o número de tarefas que podem ser executadas sem créditos. Aguarde que uma tarefa termine, ou adicione créditos.

A Meshy não conseguiu criar a tarefa devido a um erro do servidor. A Meshy reembolsa quaisquer créditos cobrados. Tente novamente o pedido.

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

id não é um ID de tarefa válido. Envie o ID result a partir da resposta de criação.

A sua equipa tem a IP Filtering ativada, e a Meshy sinalizou a imagem da tarefa de prototype por propriedade intelectual de terceiros. As tarefas de build e as equipas no plano Enterprise não recebem este erro. Crie uma tarefa de prototype a partir de uma imagem sobre a qual tem direitos de utilização.

Nenhuma tarefa Keycap com este ID pertence à sua conta, ou a fase da tarefa não corresponde ao caminho. Verifique o ID e utilize /prototype ou /build de acordo com a tarefa.

A Meshy não conseguiu executar a verificação de propriedade intelectual. Tente novamente o pedido.

O ID da tarefa a cancelar.

Aplica-se uma destas situações:

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

Nenhuma tarefa Keycap com este ID pertence à sua conta, ou a fase da tarefa não corresponde ao caminho. Verifique o ID e utilize /prototype ou /build para corresponder à tarefa.

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

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

A fase a listar, prototype ou build.

A página a devolver, de 1 a 255. 0 devolve a primeira página. Um valor fora do intervalo 0 a 255 devolve 400.

Número de tarefas por página, até 100. Um valor de 101 a 255 devolve 100 tarefas, e 0 utiliza o valor predefinido. Um valor fora do intervalo 0 a 255 devolve 400.

A ordem de ordenaçã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 de tarefa, sempre creative-lab-keycap-prototype.

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

O estado da tarefa.

Valores disponíveis:

• PENDING: em espera na fila
• IN_PROGRESS: a gerar o resultado
• SUCCEEDED: final, com o resultado
• FAILED: final, com o motivo em task_error
• CANCELED: final, sem resultado

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

Momento em que a tarefa foi criada, em milissegundos Unix.

Momento em que um worker iniciou a tarefa, em milissegundos Unix. null até isso acontecer.

Momento em que a tarefa atingiu um estado final, em milissegundos Unix. null até isso acontecer.

Momento 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 está PENDING. 1 significa que é a próxima a começar. 0 depois de a tarefa sair da fila, e sempre 0 em resultados de listagem.

Motivo pelo qual a tarefa falhou. null a menos que status seja FAILED. Consulte Erros.

Número de créditos cobrados pela tarefa, após qualquer reembolso. Um pedido que devolve um erro não é cobrado. Uma tarefa falhada é 0, porque a Meshy a reembolsa. Cancelar só reembolsa uma tarefa enquanto esta está PENDING. Se a Meshy não conseguir ler a cobrança, uma resposta de obtenção ou de streaming omite o campo, e um pedido de listagem devolve 500. Nesse caso, tente novamente o pedido.

URLs de descarregamento para a imagem do keycap acabado. O array tem um URL depois de a tarefa ser bem-sucedida, e está vazio até lá. image_urls[i] mostra o candidato em candidate_ids[i].

Estes URLs são para apresentação. O endpoint de build recebe uma entrada de candidate_ids, não um URL. São URLs assinados, por isso obtenha-os sem um cabeçalho Authorization. Mantêm-se válidos até expires_at, e obter a tarefa novamente devolve os mesmos URLs.

IDs dos candidatos, pela mesma ordem de image_urls. Para construir um candidato, envie o seu ID como candidate_id no pedido de build. Não dependa do formato destes IDs.

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

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

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

O estado da tarefa.

Valores disponíveis:

• PENDING: a aguardar na fila
• IN_PROGRESS: a gerar o resultado
• SUCCEEDED: final, com o resultado
• FAILED: final, com o motivo em task_error
• CANCELED: final, sem resultado

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

Hora em que a tarefa foi criada, em milissegundos Unix.

Hora em que um worker iniciou a tarefa, em milissegundos Unix. null até isso acontecer.

Hora em que a tarefa atingiu um estado final, em milissegundos Unix. null até isso acontecer.

Hora 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 está PENDING. 1 significa que começa a seguir. 0 depois de a tarefa sair da fila, e sempre 0 em resultados de listagem.

Motivo pelo qual a tarefa falhou. null a menos que status seja FAILED. Consulte Erros.

Número de créditos cobrados pela tarefa, após qualquer reembolso. Um pedido que devolve um erro não é cobrado. Uma tarefa falhada é 0, porque a Meshy reembolsa-a. Cancelar só reembolsa uma tarefa enquanto esta está PENDING. Se a Meshy não conseguir ler a cobrança, uma resposta de obtenção ou de stream omite o campo, e um pedido de listagem devolve 500. Nesse caso, tente novamente o pedido.

URLs de transferência para o modelo 3D. A Meshy exporta o ficheiro GLB e o pacote OBJ à escala real em milímetros, com o eixo Y para cima, com a frente do keycap virada 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 assuma que o modelo tem exatamente duas malhas.

Estes são URLs assinados, pelo que deve obtê-los sem um cabeçalho Authorization. Mantêm-se válidos até expires_at, e obter a tarefa novamente antes disso devolve os mesmos URLs. Um URL expirado não pode ser renovado, pelo que deve transferir e guardar os ficheiros antes disso.

URLs de transferência para imagens das etapas da construção, indexadas por tipo. Tal como model_urls, são URLs assinados, pelo que deve obtê-los sem um cabeçalho Authorization. Mantêm-se válidos até expires_at, e obter a tarefa novamente devolve os mesmos URLs.

Pode ter estas chaves:

• head_design: a imagem de design do candidato escolhido, que a construção transformou em 3D. Está sempre presente.
• composite: a imagem do keycap concluído para o candidato escolhido, a partir da qual a construção pintou a base. Pode estar ausente.
• base_canvas: a base do keycap pintada. Pode estar ausente.

A Meshy pode adicionar chaves, pelo que deve ignorar uma chave que não reconheça.