Creative Lab — API do chaveiro

Foto de origem para o Meshy colorizar em uma imagem conceitual pronta para chaveiro. Atualmente oferecemos suporte aos formatos .jpg, .jpeg, .png e .webp.

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

Isso rotula a tarefa em seu painel e nas listas de tarefas. Ele não é gravado no chaveiro — use name_text para isso.

Texto a ser gravado no chaveiro, como o nome de um pet ou de uma pessoa. Máximo de 10 caracteres, contados como caracteres Unicode em vez de bytes, então um nome de 10 caracteres em chinês, japonês ou coreano é aceito. Omita-o para produzir um chaveiro sem gravação.

Espaços em branco ao redor são removidos e caracteres de formatação invisíveis são eliminados antes que o texto seja usado. O valor resultante é retornado como name_text no objeto de tarefa de protótipo, para que você possa confirmar exatamente o que será gravado antes de pagar pela etapa de build.

A gravação é aplicada aqui, na etapa de protótipo. A etapa de build a herda automaticamente e não aceita um name_text próprio.

Quando definido como true, a imagem de protótipo é retornada como um PNG RGBA transparente com o fundo removido, para que você possa compor o assunto sobre qualquer fundo.

Isso controla apenas a imagem retornada por este endpoint. É separado da opção de build de mesmo nome (padrão true), que controla a remoção de fundo antes do relevo.

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 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: não foi possível baixar o image_url (404 ou timeout).
• Data URI inválido: a string base64 está malformada.
• Gravação muito longa: name_text tem mais de 10 caracteres. A requisição é rejeitada em vez de truncada, então você nunca é cobrado por um chaveiro gravado com um nome encurtado.
• Conteúdo sinalizado: a imagem de entrada foi sinalizada pela moderation de NSFW ou de propriedade intelectual, ou a gravação name_text foi sinalizada pela moderation de NSFW. A gravação é analisada apenas quanto a conteúdo NSFW — a análise de propriedade intelectual se aplica à imagem.

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

Créditos insuficientes para realizar esta tarefa.

Você excedeu seu limite de taxa.

O ID de tarefa de uma tarefa de protótipo criada por meio deste mesmo endpoint OpenAPI. O protótipo deve ter sido criado com a mesma chave de API, deve ter atingido SUCCEEDED e deve ter produzido exatamente uma imagem candidata.

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/keychain/v1/prototype e recusa qualquer outra origem com 404.

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

Silhueta do contorno do medalhão do chaveiro. Valores disponíveis:

• circle (padrão)
• rounded-rect
• hexagon
• shield
• star

Comprimento da aresta do quadrado delimitador do chaveiro, em milímetros. Intervalo: (0, 400].

Altura máxima do relevo acima da base, em milímetros. Intervalo: [0, 20].

Deslocamento vertical aplicado ao relevo antes da extrusão, em milímetros. Intervalo: [0, 20].

Espessura da placa de base plana atrás do relevo, em milímetros. Intervalo: [0, 20].

Define se a parte de trás do medalhão é vedada como uma superfície fechada. Defina como false para um shell aberto.

Curva de transferência que mapeia os valores do mapa de profundidade para a altura do relevo. Valores disponíveis:

• linear (padrão)
• gamma
• s-curve

Parâmetro de forma para a curva de transferência (relevante apenas quando relief_curve é gamma). Intervalo: (0, 10].

Inverte a interpretação do mapa de profundidade, de modo que regiões mais escuras se tornem relevo mais alto.

Intensidade de suavização aplicada ao mapa de profundidade antes da extração do relevo. Intervalo: [0, 10].

Multiplicador de escala vertical aplicado sobre relief_height_mm. Intervalo: (0, 10].

Limiar de corte para valores do mapa de profundidade; qualquer valor abaixo dele é fixado em zero. Intervalo: [0, 1].

Remove automaticamente o plano de fundo da imagem conceitual do protótipo antes de aplicar o relevo.

Independente do parâmetro de mesmo nome do protótipo (padrão false), que controla se a própria imagem do protótipo é retornada com transparência.

Resolução da malha usada para exportação. Intervalo: [64, 2048].

Pacote de artefato retornado pelo build. Valores disponíveis:

• glb (padrão) — retorna um único model.glb em model_urls.glb.
• obj — compacta model.obj + model.mtl + texture.png e retorna o pacote em model_urls.obj.
• zip — compacta todos os artefatos emitidos pelo gerador e retorna o pacote em model_urls.bundle_zip.

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

• Parâmetro ausente: input_task_id é obrigatório.
• UUID inválido: input_task_id não é um UUID válido.
• Tarefa pai não concluída com sucesso: A tarefa de protótipo referenciada ainda não atingiu SUCCEEDED.
• Nenhum candidato: A tarefa de protótipo foi bem-sucedida, mas não produziu nenhuma imagem candidata.
• Opções fora do intervalo: Um dos campos de options ficou fora do intervalo permitido ou do conjunto de valores enumerados.

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

Créditos insuficientes para realizar esta tarefa.

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

Você excedeu seu limite de taxa.

Identificador único da tarefa de chaveiro a ser recuperada.

Identificador único da tarefa de chaveiro 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 seu estágio não corresponde ao caminho da URL.

Identificador único da tarefa do chaveiro a ser transmitida.

prototype ou build. A coleção retorna apenas tarefas cujo estágio corresponde à URL — buscar em /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: 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 tarefa. Embora usemos um UUID k-sortable para os ids das tarefas como detalhe de implementação, você não deve fazer suposições sobre o formato do id.

Tipo da tarefa. O valor é creative-lab-keychain-prototype.

O nome da tarefa fornecido no momento da criação. String vazia se nenhum nome foi fornecido.

A gravação aplicada a este chaveiro, após remover espaços e caracteres de formatação invisíveis. Ausente quando a tarefa foi criada sem name_text. Compare-o com o que você enviou para confirmar que o texto sobreviveu à codificação do seu cliente HTTP.

Status da tarefa. Os valores possíveis são 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 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, esta propriedade será 0.

Carimbo de data/hora de quando a tarefa foi finalizada, em milissegundos. Se a tarefa ainda não foi finalizada, esta propriedade será 0.

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

A contagem de tarefas precedentes.

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 esta tarefa. Presente quando o status da tarefa é PENDING, IN_PROGRESS ou SUCCEEDED. Retorna 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).

URLs para download das candidatas a imagem conceitual geradas por esta tarefa de protótipo. Atualmente a API sempre retorna exatamente uma candidata; o campo é um array para que revisões futuras possam apresentar múltiplas candidatas sem uma alteração que quebre a compatibilidade.

Identificador único da tarefa.

Tipo da tarefa. O valor é creative-lab-keychain-build.

O nome da tarefa fornecido no momento da criação. String vazia se nenhum nome foi fornecido.

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

Progress da tarefa. Se a tarefa ainda não foi iniciada, esta propriedade será 0. Quando 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.

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. Significativo apenas quando o status é PENDING.

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. Retorna 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).

URLs para download do artefato gerado, indexadas pelo nome do artefato. Sempre contém exatamente uma entrada — o formato solicitado por meio do output.format da requisição de build. A chave corresponde ao formato solicitado: