Creative Lab — API do Fidget Pixel

Foto de origem para a Meshy pixelizar. Atualmente oferecemos suporte aos formatos .jpg, .jpeg, .png e .webp.

Tamanho máximo do arquivo: 20 MB.

O formato é detectado decodificando 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 suportado. Redirecionamentos HTTP são seguidos.

Há 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>.

O que a foto mostra. Seleciona o estilo de pixelização, então escolha com cuidado — os dois produzem resultados visivelmente diferentes. Valores disponíveis:

• person — o assunto é uma pessoa (retrato ou corpo inteiro). Produz um sprite de pixel estilo chibi do assunto.
• other — qualquer outra coisa: animais de estimação, objetos, mascotes, logotipos, paisagens. Produz um ícone de pixel estilo bead-art do assunto.

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

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

• Parâmetro ausente: image_url e type são ambos obrigatórios.
• Tipo inválido: type deve ser person ou other.
• 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: Não foi possível baixar o image_url (404 ou timeout).
• Data URI inválido: A string base64 está malformada.
• Conteúdo sinalizado: A imagem de entrada foi sinalizada pela moderation de NSFW.

Falha na autenticação. Por favor, verifique sua chave de API.

Créditos insuficientes para executar esta tarefa, ou a chave de API pertence a uma conta do plano gratuito.

A imagem de entrada foi sinalizada pela moderation de propriedade intelectual (Content flagged for intellectual property violation). Apenas contas Enterprise com a filtragem de propriedade intelectual ativada são bloqueadas; nada é cobrado.

Você excedeu seu limite de taxa.

A própria verificação de propriedade intelectual não pôde ser concluída (Unable to perform intellectual property check, please try again). Contas Enterprise com a filtragem de propriedade intelectual ativada falham de forma restritiva nessa verificação; nada é cobrado — tente a solicitação novamente.

O ID da tarefa de uma tarefa de protótipo criada por meio deste mesmo endpoint OpenAPI. O protótipo deve ter sido criado pela mesma conta Meshy e deve ter alcançado SUCCEEDED.

Tarefas de protótipo criadas por meio do webapp não são aceitas — o endpoint de build aceita apenas tarefas de protótipo produzidas por POST /openapi/creative-lab/fidget-pixel/v1/prototype e recusa qualquer outra origem com 404.

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

Formato de cada peça. Valores disponíveis:

• square (padrão) — peças quadradas em uma grade quadrada.
• hex — peças hexagonais em uma grade hexagonal. Peças hexagonais estão disponíveis apenas em 6 e 8 mm.

Número de peças ao longo de cada lado do tabuleiro. Valores disponíveis: 16 ou 32. Uma grade 32 mantém mais detalhes; uma grade 16 significa peças menos numerosas e maiores para o mesmo assunto.

Comprimento da aresta de cada peça, em milímetros. Valores disponíveis: 6, 8, ou 10. Junto com grid_size, isso define o tamanho do tabuleiro impresso — por exemplo, 32 × 8 mm ≈ 26 cm por lado. 10 não está disponível para shape: "hex" (a face hexagonal inclinada gera balanços (overhangs) na maioria das impressoras FDM de consumo).

Número máximo de cores na paleta para a qual a imagem é quantizada. Intervalo: [1, 8]. Cada cor se torna um filamento no seu fatiador.

Altura de cada peça, em milímetros. Intervalo: [10, 80].

Artefato retornado pelo build. Valores disponíveis:

• 3mf (padrão) — retorna um único model.3mf em model_urls.3mf, com um objeto por peça e a cor da peça anexada a cada objeto.

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

• Parâmetro ausente: input_task_id é obrigatório.
• UUID inválido: O input_task_id não é um UUID válido.
• Origem não bem-sucedida: A tarefa de protótipo referenciada ainda não alcançou SUCCEEDED.
• Nenhum candidato: A tarefa de protótipo foi bem-sucedida, mas não produziu nenhuma imagem em pixel art; crie um novo protótipo.
• Opções fora do intervalo: Um dos campos de options está fora do conjunto ou intervalo permitido — por exemplo options.grid_size must be 16 or 32, ou options.piece_size_mm=10 is not supported for shape=hex; hex pieces are available in 6 and 8 mm.
• Formato não suportado: output.format deve ser 3mf.

Falha na autenticação. Verifique sua chave de API.

Créditos insuficientes para realizar esta tarefa, ou a chave de API pertence a uma conta do plano gratuito.

A imagem do protótipo referenciado foi sinalizada pela moderation de propriedade intelectual. Apenas contas Enterprise com filtragem de propriedade intelectual habilitada são bloqueadas; nada é cobrado.

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

Você excedeu seu limite de taxa.

Não foi possível estabelecer o veredito de propriedade intelectual do protótipo referenciado (Unable to perform intellectual property check, please try again). Contas Enterprise com filtragem de propriedade intelectual habilitada falham de forma fechada nesta verificação; nada é cobrado — tente a requisição novamente.

Identificador único da tarefa do fidget pixel a ser recuperada.

id não é um UUID válido (Invalid ID).

A imagem da tarefa foi sinalizada pela moderação de propriedade intelectual. Apenas contas Enterprise com filtragem de propriedade intelectual ativada são bloqueadas.

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

A verificação de propriedade intelectual não pôde ser concluída (Unable to perform intellectual property check, please try again); contas Enterprise com filtragem de propriedade intelectual ativada falham de forma restritiva. Tente a requisição novamente.

Identificador único da tarefa fidget pixel a ser cancelada.

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

• ID inválido: id não é um UUID válido.
• Estado terminal: A tarefa já está SUCCEEDED, FAILED ou CANCELED 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.

Identificador único da tarefa fidget pixel a ser transmitida.

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

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

Identificador único da task. Embora usemos um UUID k-sortable para ids de tasks como detalhe de implementação, você não deve fazer suposições sobre o formato do id.

Tipo da task. O valor é creative-lab-fidget-pixel-prototype.

O nome da task fornecido quando ela foi criada. String vazia se nenhum nome foi fornecido.

Status da task. Os valores possíveis são um de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progress da task. Se a task ainda não foi iniciada, essa propriedade será 0. Assim que a task for concluída com sucesso, ela se tornará 100.

Carimbo de data/hora de quando a task foi criada, em milissegundos.

Carimbo de data/hora de quando a task foi iniciada, em milissegundos. Se a task ainda não foi iniciada, essa propriedade será null.

Carimbo de data/hora de quando a task foi finalizada, em milissegundos. Se a task ainda não foi finalizada, essa propriedade será null.

Carimbo de data/hora de quando o resultado da task expira, em milissegundos — 3 dias após a conclusão da task. Contas Enterprise mantêm os resultados da API indefinidamente (veja Retenção de Recursos); para elas, esse carimbo de data/hora é definido para cerca de 100 anos no futuro.

A contagem de tasks precedentes.

Detalhes de erro para tasks que falharam. Veja Erros para a referência completa do objeto task_error.

O número de créditos consumidos por essa task. Uma task que atinge SUCCEEDED é cobrada pelo valor total de sua etapa. Uma task que nunca chega a ser criada (um 4xx no momento da solicitação, incluindo uma rejeição de moderation) não é cobrada de forma alguma. Uma task que atinge FAILED retorna 0 — a cobrança é reembolsada. Cancelar via DELETE reembolsa somente enquanto a task ainda está PENDING; uma task já IN_PROGRESS permanece cobrada, pois o trabalho já foi realizado.

URLs para download da imagem em pixel art gerada por essa task de prototype. Atualmente a API sempre retorna exatamente uma imagem; o campo é um array para que revisões futuras possam apresentar múltiplos candidatos sem uma alteração incompatível. Vazio até que a task atinja SUCCEEDED.

Essas 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 task dentro dessa janela retorna a mesma URL, em vez de uma recém-assinada. Faça o download e armazene os arquivos você mesmo antes disso — não há como atualizar um link expirado.

Identificador único da tarefa.

Tipo da tarefa. O valor é creative-lab-fidget-pixel-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 de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progresso da tarefa. Se a tarefa ainda não foi iniciada, esta propriedade será 0. Assim que a tarefa for bem-sucedida, 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. null até a tarefa começar.

Carimbo de data/hora de quando a tarefa foi finalizada, em milissegundos. null até a tarefa terminar.

Carimbo de data/hora de quando o resultado da tarefa expira, em milissegundos — 3 dias após a tarefa terminar. Contas Enterprise mantêm os resultados da API indefinidamente (veja Retenção de Recursos); para elas, esse carimbo de data/hora é definido para cerca de 100 anos no futuro.

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

Detalhes do erro para tarefas com falha. 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 o valor integral para o seu estágio. 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. Cancelar via DELETE só reembolsa enquanto a tarefa ainda está PENDING; uma tarefa já IN_PROGRESS permanece cobrada, pois o trabalho já foi gasto.

URLs para download do artefato gerado, indexadas por formato. Contém exatamente uma entrada — o formato solicitado através do output.format da requisição de build. Vazio até a tarefa atingir SUCCEEDED.

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 dessa janela retorna a mesma URL, em vez de uma recém-assinada. Baixe e armazene os arquivos você mesmo antes disso — não há como atualizar um link expirado.