Creative Lab — API do Fidget Pixel

Foto de origem para o Meshy pixelizar. Atualmente suportamos os formatos .jpg, .jpeg, .png e .webp.

O formato é detectado ao decodificar os dados da imagem, não pela extensão do arquivo na URL — uma URL sem extensão, ou uma que redirecione, 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 a partir da internet pública.
• Data URI: Um Data URI da imagem codificado em base64. Exemplo de um Data URI: data:image/jpeg;base64,<your base64-encoded image data>.

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

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

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

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

• Parâmetro ausente: image_url e type são ambos obrigatórios.
• Type 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 da 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 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 realizar 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). Somente contas Enterprise com filtragem de propriedade intelectual habilitada 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 filtragem de propriedade intelectual habilitada falham de forma fechada (fail closed) nesta verificação; nada é cobrado — tente novamente a requisição.

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.