Creative Lab — API de Figure

Foto de origem para a Meshy estilizar como uma figura chibi. Atualmente oferecemos suporte aos formatos .jpg, .jpeg, .png e .webp.

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

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

Quando definido como true, a imagem prototípica é retornada como um PNG RGBA transparente com o fundo removido, para que você possa compor o assunto sobre qualquer fundo.

A requisição não foi aceitá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 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: 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 ou propriedade intelectual.

A autenticação falhou. Por favor, verifique sua chave de API.

Créditos insuficientes para realizar esta tarefa.

Você excedeu seu limite de taxa.

O ID da tarefa de uma tarefa de protótipo criada através 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 através da webapp não são aceitas — o endpoint de build aceita apenas tarefas de protótipo produzidas por POST /openapi/creative-lab/figure/v1/prototype e recusa qualquer outra origem com 404.

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: input_task_id é obrigatório.
• UUID inválido: O input_task_id não é um UUID válido.
• Origem 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.

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 um usuário diferente ou foi criada através da webapp (apenas tarefas de protótipo em modo API se encadeiam em um build).

Você excedeu seu limite de taxa.

Identificador único da tarefa de figura a ser recuperada.

Identificador único da tarefa de figure 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 de figure a ser transmitida.

Pode ser 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 de itens por página. O máximo permitido é 100 itens.

Campo pelo qual ordenar. 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 de tarefa como detalhe de implementação, você não deve fazer suposições sobre o formato do id.

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

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, essa 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, essa propriedade será 0.

Carimbo de data/hora de quando a tarefa foi finalizada, em milissegundos. Se a tarefa ainda não foi finalizada, essa 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 essa 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 essa tarefa de prototipagem. Atualmente, a API sempre retorna exatamente uma candidata; o campo é um array para que revisões futuras possam expor múltiplas candidatas sem uma alteração que quebre a compatibilidade.

Identificador único da tarefa.

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

O nome da tarefa fornecido quando ela 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, essa propriedade será 0. Uma vez que a tarefa tenha sido concluída com sucesso, 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 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. Retorna 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).

Sempre vazio para construção de figura. Presente para compatibilidade entre endpoints com o formato compartilhado V2ImageTo3DTaskResponse usado por Imagem para 3D.

Sempre vazio para construção de figura. Presente para compatibilidade entre endpoints.

Sempre vazio para construção de figura. Presente para compatibilidade entre endpoints.

Sempre vazio para construção de figura. Presente para compatibilidade entre endpoints.

URLs para download do modelo 3D gerado. A construção da figura emite um GLB texturizado além do par OBJ + MTL para pipelines que preferem o Wavefront OBJ. O formato do campo corresponde ao objeto model_urls do Imagem para 3D, de forma que futuras adições de formato se encaixem sem uma alteração de ruptura.

URL para download da imagem de miniatura do arquivo do modelo.

Um array de objetos de URL de textura gerados por esta tarefa. Atualmente contém um único objeto com o mapa de cor base.