Creative Lab — API de Porta-chaves

Fotografia de origem para a Meshy colorizar numa imagem de conceito pronta para porta-chaves. Atualmente suportamos os formatos .jpg, .jpeg, .png e .webp.

Existem duas formas de fornecer a imagem:

• URL publicamente acessível: Um URL 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>.

Nome de tarefa opcional para fins de apresentação. Máximo de 100 carateres.

Isto identifica a tarefa no seu painel e nas listas de tarefas. Não é gravado no porta-chaves — utilize name_text para isso.

Texto a gravar no porta-chaves, como o nome de um animal de estimação ou de uma pessoa. Máximo de 10 carateres, contados como carateres Unicode em vez de bytes, pelo que um nome chinês, japonês ou coreano com 10 carateres é aceite. Omita-o para produzir um porta-chaves sem gravação.

Os espaços em branco circundantes são removidos e os carateres de formatação invisíveis são eliminados antes de o texto ser utilizado. O valor resultante é devolvido como name_text no objeto de tarefa de protótipo, para que possa confirmar exatamente o que será gravado antes de pagar pela fase de construção.

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

Quando definido como true, a imagem do protótipo é devolvida como um PNG RGBA transparente com o fundo removido, para que possa compor o sujeito sobre qualquer fundo.

Isto controla apenas a imagem devolvida por este endpoint. É independente da opção de construção com o mesmo nome (predefinição true), que controla a remoção do fundo antes do relevo.

O pedido foi inaceitável. Causas comuns:

• Parâmetro em falta: image_url é obrigatório.
• Formato de imagem inválido: O image_url fornecido não é um formato suportado (.jpg, .jpeg, .png, .webp).
• Dimensões da imagem fora do intervalo: A imagem é demasiado pequena, excede o tamanho máximo de ficheiro ou excede o número máximo de píxeis.
• URL inacessível: Não foi possível transferir o image_url (404 ou timeout).
• Data URI inválido: A string base64 está malformada.
• Gravação demasiado longa: name_text tem mais de 10 carateres. O pedido é rejeitado em vez de truncado, pelo que nunca é cobrado por um porta-chaves gravado com um nome encurtado.
• Conteúdo assinalado: A imagem de entrada foi assinalada pela moderation de NSFW ou de propriedade intelectual, ou a gravação name_text foi assinalada pela moderation de NSFW. A gravação é filtrada apenas para conteúdo NSFW — a filtragem de propriedade intelectual aplica-se à imagem.

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

Créditos insuficientes para realizar esta tarefa.

Excedeu o seu limite de taxa.

O ID da tarefa de um protótipo criado através deste mesmo endpoint de OpenAPI. O protótipo tem de ter sido criado com a mesma chave de API, tem de ter atingido SUCCEEDED e tem de ter produzido exatamente uma imagem candidata.

Tarefas de protótipo criadas através da aplicação web não são aceites — o endpoint de construção aceita apenas tarefas de protótipo produzidas por POST /openapi/creative-lab/keychain/v1/prototype e rejeita qualquer outra origem com 404.

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

Silhueta do contorno do medalhão do porta-chaves. Valores disponíveis:

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

Comprimento do lado do quadrado delimitador do porta-chaves, 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 base plana por trás do relevo, em milímetros. Intervalo: [0, 20].

Se a parte de trás do medalhão está selada como uma superfície fechada. Defina como false para um invólucro aberto.

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

• linear (predefinição)
• gamma
• s-curve

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

Inverte a interpretação do mapa de profundidade para que as regiões mais escuras se tornem em relevo mais elevado.

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 passa-baixo para os valores do mapa de profundidade; tudo o que estiver abaixo deste valor é reduzido a zero. Intervalo: [0, 1].

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

Distinto do parâmetro do protótipo com o mesmo nome (predefinição false), que controla se a própria imagem do protótipo é devolvida com transparência.

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

Conjunto de artefactos devolvido pela construção. Valores disponíveis:

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

O pedido foi inaceitável. Causas comuns:

• Parâmetro em falta: input_task_id é obrigatório.
• UUID inválido: input_task_id não é um UUID válido.
• Tarefa principal sem sucesso: A tarefa de protótipo referenciada ainda não atingiu SUCCEEDED.
• Sem candidata: A tarefa de protótipo teve sucesso, mas não produziu nenhuma imagem candidata.
• Opções fora do intervalo: Um dos campos de options está fora do intervalo permitido ou do conjunto de valores enumerados.

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

Créditos insuficientes para realizar esta tarefa.

A tarefa de protótipo referenciada não existe, pertence a um utilizador diferente ou foi criada através da aplicação web (apenas tarefas de protótipo em modo API se encadeiam na construção).

Excedeu o seu limite de taxa.

Identificador único da tarefa de porta-chaves a obter.

Identificador único da tarefa de porta-chaves a cancelar.

A tarefa já se encontra num estado terminal e não pode ser cancelada.

A tarefa não existe, pertence a um utilizador diferente, ou a sua fase não corresponde ao caminho do URL.

Identificador único da tarefa de porta-chaves a transmitir.

prototype ou build. A coleção retorna apenas as tarefas cuja etapa corresponde ao URL — obter /prototype nunca retorna tarefas de construção e vice-versa.

Número da página para paginação.

Limite do tamanho da página. O máximo permitido é 100 itens.

Campo pelo qual ordenar. Valores disponíveis:

• +created_at: Ordenar por hora de criação em ordem ascendente.
• -created_at: Ordenar por hora de criação em ordem descendente.

Identificador único da tarefa. Embora utilizemos um UUID k-sortable para os ids das tarefas como detalhe de implementação, não deve fazer nenhuma suposição sobre o formato do id.

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

O nome da tarefa fornecido no momento da criação. Cadeia vazia se não tiver sido fornecido nenhum nome.

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

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

Progress da tarefa. Se a tarefa ainda não tiver começado, esta propriedade será 0. Assim que a tarefa for concluída com sucesso, passará a ser 100.

Carimbo de data/hora da criação da tarefa, em milissegundos.

Carimbo de data/hora do início da tarefa, em milissegundos. Se a tarefa ainda não tiver começado, esta propriedade será 0.

Carimbo de data/hora da conclusão da tarefa, em milissegundos. Se a tarefa ainda não tiver terminado, esta propriedade será 0.

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

A contagem de tarefas precedentes.

Detalhes do erro para tarefas falhadas. Consulte Erros para a referência completa do objeto task_error.

O número de créditos consumidos por esta tarefa. Presente quando o estado da tarefa é PENDING, IN_PROGRESS, ou SUCCEEDED. Devolve 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).

URLs transferíveis para os candidatos a imagem de conceito gerados por esta tarefa de protótipo. Atualmente, a API devolve sempre exatamente um candidato; o campo é um array para que revisões futuras possam apresentar vários candidatos sem introduzir uma alteração de rutura.

Identificador único da tarefa.

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

O nome da tarefa fornecido no momento da criação da tarefa. Cadeia de caracteres vazia se não tiver sido fornecido nenhum nome.

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

Progress da tarefa. Se a tarefa ainda não tiver começado, esta propriedade será 0. Uma vez que a tarefa tenha sido bem-sucedida, passará a ser 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 concluída, em milissegundos.

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

A contagem de tarefas precedentes. Apenas relevante 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. Devolve 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).

URLs para transferência do artefacto gerado, indexados pelo nome do artefacto. Contém sempre exatamente uma entrada — o formato solicitado através do output.format do pedido de compilação. A chave corresponde ao formato solicitado: