Creative Lab — API de Luminária

Foto de origem que a Meshy usa como referência visual para a cúpula da luminária. Atualmente oferecemos suporte aos formatos .jpg, .jpeg, .png e .webp.

Há duas maneiras de fornecer a imagem:

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

Dica de categoria de assunto que seleciona o prompt de estilização. Valores disponíveis:

• character (padrão) — assunto de personagem/objeto único (boneco, animal, mascote, etc.).
• landscape — assunto de cena externa/panorama (montanha, paisagem urbana, floresta, etc.).

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

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

A solicitação foi 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 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 moderação de NSFW ou de propriedade intelectual.
• image_subject inválido: Não é character nem landscape.

A autenticação falhou. 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 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 um modelo 3D.

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

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

Dimensão máxima alvo da caixa delimitadora da cúpula da luminária, em milímetros. A malha é escalada uniformemente para se ajustar. Intervalo: [50, 400].

Espessura de parede da cúpula oca da luminária, em milímetros. Intervalo: (0, 10].

Percentual da altura do modelo cortado de forma plana na parte inferior, para que a cúpula da luminária se apoie na mesa de impressão e tenha uma abertura para a fixação. Intervalo: [1, 100].

Preset de fixação da fonte de luz que determina como a parte inferior é construída. Valores disponíveis:

• bambu_mh001_60mm (padrão) — cúpula de luminária com fundo aberto mais uma placa base contendo um furo de fixação de 60 mm, ambos em model_urls.lamp_stl, e o suporte de fixação como model_urls.base_stl.
• none — uma única cúpula de luminária selada em model_urls.lamp_stl; model_urls.base_stl é omitido.

Deslocamento no eixo X do furo de fixação na placa base, relativo ao centro da cúpula da luminária, em milímetros. Só faz sentido quando light_source_preset ≠ none. Intervalo: [-80, 80].

Deslocamento no eixo Z (profundidade) do furo de fixação na placa base, relativo ao centro da cúpula da luminária, em milímetros. Só faz sentido quando light_source_preset ≠ none. Intervalo: [-80, 80].

Rotação em torno do eixo X aplicada ao modelo antes do processamento, em graus. As três rotações são aplicadas como ângulos de Euler XYZ em torno do centro do modelo. Intervalo: [-360, 360].

Rotação em torno do eixo Y aplicada à malha importada antes do processamento, em graus. Intervalo: [-360, 360].

Rotação em torno do eixo Z aplicada à malha importada antes do processamento, em graus. Intervalo: [-360, 360].

Quando true e output.format é zip, inclui o result.json do processador de luminária (nome do pipeline, avisos e caminhos dos artefatos) dentro do pacote. Ignorado quando output.format é stl.

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

• stl (padrão) — retorna model_urls.lamp_stl (a cúpula da luminária, junto com a placa base quando um preset de fixação é definido), além de model_urls.base_stl quando light_source_preset ≠ none.
• zip — empacota todos os artefatos que o processador emite (lamp.stl, base.stl opcional, result.json opcional) em um único zip e o retorna em model_urls.bundle_zip.

A solicitaçã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.
• Pai não bem-sucedido: A tarefa de protótipo referenciada ainda não atingiu SUCCEEDED.
• Sem modelo: A tarefa de protótipo foi bem-sucedida, mas não produziu nenhum modelo 3D.
• Opções fora do intervalo: Um dos campos de options estava 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 um usuário diferente ou foi criada por meio da webapp (apenas tarefas de protótipo em modo API se encadeiam ao build).

Você excedeu seu limite de taxa.

Identificador único da tarefa de luminária a ser recuperada.

Identificador único da tarefa de luminária a ser cancelada.

A tarefa já está em um estado terminal e não pode ser cancelada.

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

Identificador único da tarefa de luminária a ser transmitida.

prototype ou build. A coleção retorna apenas tarefas cujo estágio corresponda à URL — buscar /prototype nunca retorna tarefas de construção e vice-versa.

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

Limite de tamanho da página. O máximo permitido é 50 itens.

Campo pelo qual ordenar. Valores disponíveis:

• +created_at: Ordena pelo horário de criação em ordem crescente.
• -created_at: Ordena 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-lamp-prototype.

O nome da tarefa fornecido quando a tarefa foi criada. Uma string vazia se nenhum nome foi fornecido.

Status da tarefa. Os valores possíveis são um dos seguintes: 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 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. 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 do modelo 3D gerado a partir da imagem conceitual. Presente assim que a tarefa for concluída com sucesso; {} antes disso.

URL para download de uma pré-visualização renderizada do modelo 3D. String vazia até que a tarefa seja concluída com sucesso.

URLs para download dos candidatos de imagem conceitual gerados por esta tarefa de protótipo. Atualmente, a API sempre retorna exatamente um candidato; o campo é um array para que futuras revisões possam apresentar múltiplos candidatos sem uma alteração incompatível.

Identificador único da tarefa.

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

O nome da tarefa fornecido no momento da criação da tarefa. 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. Quando 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.

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 dos artefatos gerados, indexadas pelo nome do artefato. O conjunto de chaves depende de output.format e options.light_source_preset: