Transforme uma foto de origem em uma minifigura colecionável em estilo brick em duas etapas:
protótipo gera uma imagem conceitual estilizada a partir da sua foto de entrada, em seguida
construção transforma essa imagem conceitual em um modelo 3D com textura. As duas etapas
estão vinculadas via input_task_id.
POST /openapi/creative-lab/brick-figure/v1/prototype
Gere uma imagem de conceito em estilo de blocos a partir da foto de origem. O
ID de tarefa retornado é o que você passa como input_task_id para o endpoint de construção. Consulte
O Objeto de Tarefa de Protótipo de Figura de Brick
para o formato da resposta.
Parâmetros
Name
image_url
Type
string
Obrigatório
Description
Foto de origem para Meshy estilizar como uma minifigura de blocos. Atualmente suportamos os formatos .jpg, .jpeg, .png, e .webp.
Existem duas maneiras de fornecer a imagem:
URL acessível publicamente: Um URL que está acessível da internet pública.
Data URI: Um Data URI codificado em base64 da imagem. Exemplo de um Data URI: data:image/jpeg;base64,<seus dados de imagem codificados em base64>.
Name
name
Type
string
Description
Nome de tarefa opcional para fins de exibição. Máximo de 100 caracteres.
Retornos
A propriedade result da resposta contém o id da tarefa recém-criada de protótipo de figura de blocos. Consulte o endpoint Obter uma Tarefa ou assine o stream até que a tarefa alcance SUCCEEDED, então passe esse ID para o endpoint de construção como input_task_id.
Modos de Falha
Name
400 - Bad Request
Description
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 é um formato suportado (.jpg, .jpeg, .png, .webp).
Dimensões da imagem fora do alcance: A imagem é muito pequena, excede o tamanho máximo de arquivo, ou excede o número máximo 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 por moderação NSFW ou de propriedade intelectual.
Name
401 - Unauthorized
Description
A autenticação falhou. Por favor, verifique sua chave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarefa.
Name
403 - Forbidden
Description
A imagem de entrada foi sinalizada por violação de propriedade intelectual.
Name
429 - Too Many Requests
Description
Você excedeu o seu limite de taxa.
Request
POST
/openapi/creative-lab/brick-figure/v1/prototype
# Etapa 1: gerar uma imagem de conceito em estilo de blocoscurl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/prototype \ -X POST \ -H "Authorization: Bearer ${YOUR_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ "image_url": "<seu URL de imagem acessível publicamente ou Data URI codificado em base64>" }'
Gere a figura final de brick 3D texturizada a partir de uma tarefa de protótipo bem-sucedida. A construção executa o mesmo pipeline de imagem-para-3D que Imagem para 3D, portanto, o formato do objeto de resposta e a lista de URLs de saída correspondem exatamente. Consulte O Objeto de Tarefa de Construção de Figura Brick para a forma da resposta.
Parâmetros
Name
input_task_id
Type
string
Obrigatório
Description
O ID da tarefa de um protótipo criado através deste mesmo endpoint OpenAPI. O protótipo deve ter sido criado com a mesma chave de API, deve ter alcançado SUCCEEDED e deve ter produzido exatamente uma imagem candidata.
Tarefas de protótipo criadas através do webapp não são aceitas — o endpoint de construção aceita apenas tarefas de protótipo produzidas por POST /openapi/creative-lab/brick-figure/v1/prototype e recusa qualquer outra origem com 404.
Name
name
Type
string
Description
Nome opcional da tarefa para fins de exibição. Máximo de 100 caracteres.
Retornos
A propriedade result da resposta contém o id da tarefa da nova construção de figura de brick criada. Acompanhe o endpoint Obter uma Tarefa ou inscreva-se no stream até que a tarefa alcance SUCCEEDED, depois baixe o GLB texturizado de model_urls.glb (ou o par OBJ + MTL de model_urls.obj e model_urls.mtl se seu pipeline preferir OBJ).
Modos de Falha
Name
400 - Bad Request
Description
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.
Protótipo não sucedido: 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 imagem candidata.
Name
401 - Unauthorized
Description
Falha na autenticação. Por favor, verifique sua chave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para executar esta tarefa.
Name
404 - Not Found
Description
A tarefa de protótipo referenciada não existe, pertence a outro usuário ou foi criada através do webapp (somente tarefas de protótipo em modo API são encadeadas para construção).
Name
429 - Too Many Requests
Description
Você excedeu seu limite de taxa.
Solicitação
POST
/openapi/creative-lab/brick-figure/v1/build
# Etapa 2: encadear construção a partir de uma tarefa de protótipo bem-sucedidacurl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/build \ -X POST \ -H "Authorization: Bearer ${YOUR_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578" }'
Recupere uma tarefa de protótipo ou construção dada um id de tarefa válido. O caminho do URL
deve corresponder ao estágio da tarefa — uma tarefa de construção buscada através de
/prototype/:id retorna 404, e vice-versa.
Cancelar uma tarefa de figura de bloco. Se a tarefa ainda estiver PENDING, os créditos
consumidos no momento da criação são reembolsados. Tarefas que já estão
IN_PROGRESS são canceladas sem reembolso (o trabalhador já pode estar
consumindo recursos). Tarefas que já alcançaram um estado terminal
(SUCCEEDED, FAILED, CANCELED) não podem ser canceladas.
O caminho da URL deve corresponder ao estágio da tarefa — DELETE em
/prototype/:buildId retorna 404.
Parâmetros de Caminho
Name
id
Type
path
Description
Identificador único para a tarefa de figura de bloco a ser cancelada.
Retornos
Retorna 204 No Content com sucesso e com corpo vazio.
Modos de Falha
Name
400 - Bad Request
Description
A tarefa já está em um estado terminal e não pode ser cancelada.
Name
404 - Not Found
Description
A tarefa não existe, pertence a um usuário diferente, ou seu estágio não corresponde ao caminho da URL.
Transmita atualizações em tempo real para uma tarefa de figura de tijolos via Server-Sent Events (SSE).
O caminho da URL deve corresponder ao estágio da tarefa — abrir um stream em
/prototype/:buildId/stream emite um único event: error payload com
status_code: 404 e fecha o stream.
Parâmetros
Name
id
Type
path
Description
Identificador único para a tarefa de figura de tijolos a ser transmitida.
Retornos
Retorna um fluxo de objetos de tarefa Figura de Tijolos Protótipo
ou Figura de Tijolos Construção como
Server-Sent Events. Para tarefas PENDING ou IN_PROGRESS, o fluxo de resposta
incluirá apenas os campos necessários progress e status.
// Exemplo de evento de erro (estágio errado ou tarefa não encontrada)event: errordata: {"status_code": 404,"message": "Task not found"}// Exemplos de eventos de mensagem ilustram o progresso da tarefa.// Para tarefas PENDING ou IN_PROGRESS, o fluxo de resposta não incluirá todos os campos.event: messagedata: {"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb","progress": 0,"status": "PENDING"}event: messagedata: {"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb","type": "creative-lab-brick-figure-build","status": "SUCCEEDED","progress": 100,"created_at": 1729123500000,"started_at": 1729123510000,"finished_at": 1729123535000,"expires_at": 1729382735000,"task_error": null,"consumed_credits": 30,"prompt": "","negative_prompt": "","texture_prompt": "","texture_image_url": "","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***","obj":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***" },"thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***" } ]}
Recupere uma lista paginada de suas tarefas de figura de tijolo para um único estágio. O caminho da URL
seleciona o estágio — /prototype retorna tarefas de protótipo; /build
retorna tarefas de construção. Tarefas de outro estágio não estão incluídas em nenhuma
resposta.
Parâmetros de Caminho
Name
stage
Type
path
Obrigatório
Description
Ou 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.
Parâmetros de Consulta
Name
page_num
Type
integer
padrão 1
Description
Número da página para paginação.
Name
page_size
Type
integer
padrão 10
Description
Limite de tamanho da página. O máximo permitido é 100 itens.
Name
sort_by
Type
string
padrão -created_at
Description
Campo para classificar. Valores disponíveis:
+created_at: Ordenar por tempo de criação em ordem ascendente.
-created_at: Ordenar por tempo de criação em ordem descendente.
O objeto de tarefa do Protótipo de Figura de Tijolos é uma unidade de trabalho que a Meshy acompanha para gerar uma imagem conceitual em estilo de tijolo a partir de uma foto fonte. A saída desta etapa é encadeada na etapa de construção via input_task_id.
Propriedades
Name
id
Type
string
Description
Identificador único para a tarefa. Embora usemos um UUID k-sortable para ids de tarefa como detalhe de implementação, você não deve fazer suposições sobre o formato do id.
Name
type
Type
string
Description
Tipo da tarefa. O valor é creative-lab-brick-figure-prototype.
Name
name
Type
string
Description
O nome da tarefa fornecido quando a tarefa foi criada. String vazia se nenhum nome foi fornecido.
Name
status
Type
string
Description
Status da tarefa. Os valores possíveis são um entre PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progresso da tarefa. Se a tarefa ainda não tiver iniciado, esta propriedade será 0. Uma vez que a tarefa tenha sido concluída com sucesso, isso se tornará 100.
Name
created_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi criada, em milissegundos.
Um carimbo de data/hora representa o número de milissegundos decorridos desde 1º de janeiro de 1970 UTC, seguindo
o padrão RFC 3339.
Por exemplo, sexta-feira, 1º de setembro de 2023 às 12:00:00 PM GMT é representado como 1693569600000. Isso se aplica
a todos os carimbos de data/hora na Meshy API.
Name
started_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi iniciada, em milissegundos. Se a tarefa ainda não tiver iniciado, esta propriedade será null.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi finalizada, em milissegundos. Se a tarefa ainda não foi finalizada, esta propriedade será null.
Name
expires_at
Type
timestamp
Description
Carimbo de data/hora de quando o resultado da tarefa expira, em milissegundos.
Name
preceding_tasks
Type
integer
Description
A contagem de tarefas precedentes.
O valor deste campo é significativo apenas se o status da tarefa for PENDING.
Name
task_error
Type
object
Description
Detalhes de erro para tarefas falhas. Veja Erros para a referência completa do objeto task_error.
Name
consumed_credits
Type
integer
Description
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 (créditos são reembolsados em caso de falha).
Name
image_urls
Type
array of strings
Description
URLs para download dos candidatos de imagem conceito gerados por esta tarefa protótipo. Atualmente, a API sempre retorna exatamente um candidato; o campo é um array para que revisões futuras possam apresentar múltiplos candidatos sem uma mudança de ruptura.
Exemplo de Objeto de Tarefa Protótipo de Figura de Tijolos
O objeto de Tarefa de Construção de Figura de Tijolo é uma unidade de trabalho que a Meshy acompanha para
gerar uma figura de tijolo 3D texturizada a partir de uma tarefa de protótipo SUCCEEDED. Ele
executa o mesmo pipeline de imagem para 3D utilizado por Imagem para 3D,
portanto os campos de saída espelham o objeto de tarefa daquele endpoint.
Propriedades
Name
id
Type
string
Description
Identificador único para a tarefa.
Name
type
Type
string
Description
Tipo da tarefa. O valor é creative-lab-brick-figure-build.
Name
name
Type
string
Description
O nome da tarefa fornecido quando a tarefa foi criada. Cadeia de caracteres vazia se nenhum nome foi fornecido.
Name
status
Type
string
Description
Status da tarefa. Os valores possíveis são um de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progresso da tarefa. Se a tarefa ainda não foi iniciada, esta propriedade será 0. Uma vez que a tarefa tenha sido concluída com sucesso, isso se tornará 100.
Name
created_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi criada, em milissegundos.
Name
started_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi iniciada, em milissegundos.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi finalizada, em milissegundos.
Name
expires_at
Type
timestamp
Description
Carimbo de data/hora de quando o resultado da tarefa expira, em milissegundos.
Name
preceding_tasks
Type
integer
Description
A contagem de tarefas precedentes. Significativo somente quando o status é PENDING.
Name
task_error
Type
object
Description
Detalhes do erro para tarefas falhas. Veja Errors para a referência completa do objeto task_error.
Name
consumed_credits
Type
integer
Description
O número de créditos consumidos por esta tarefa. Retorna 0 para tarefas FAILED (créditos são reembolsados em caso de falha).
Name
prompt
Type
string
Description
Sempre vazio para construção de figura de tijolos. Presente para compatibilidade entre endpoints compartilhados V2ImageTo3DTaskResponse usado por Imagem para 3D.
Name
negative_prompt
Type
string
Description
Sempre vazio para construção de figura de tijolos. Presente para compatibilidade entre endpoints.
Name
texture_prompt
Type
string
Description
Sempre vazio para construção de figura de tijolos. Presente para compatibilidade entre endpoints.
Name
texture_image_url
Type
string
Description
Sempre vazio para construção de figura de tijolos. Presente para compatibilidade entre endpoints.
Name
model_urls
Type
object
Description
URLs para download do modelo 3D gerado. A construção de figura de tijolos emite um GLB texturizado mais o par OBJ + MTL para pipelines que preferem Wavefront OBJ. O formato do campo corresponde ao objeto Image to 3D model_urls para que futuras adições de formato se encaixem sem uma mudança disruptiva.
Name
glb
Type
string
Description
URL para download do arquivo GLB texturizado.
Name
obj
Type
string
Description
URL para download do arquivo Wavefront OBJ (geometria + UV).
Name
mtl
Type
string
Description
URL para download do arquivo de material MTL companheiro do OBJ. Combinado com obj e a entrada de texture_urls[0].base_color.
Name
thumbnail_url
Type
string
Description
URL para download da imagem em miniatura do arquivo do modelo.
Name
texture_urls
Type
array
Description
Um array de objetos URL de textura gerados por esta tarefa. Atualmente contém um único objeto com o mapa de cor base.
Name
base_color
Type
string
Description
URL para download da imagem do mapa de cor base.
Exemplo de Objeto de Tarefa de Construção de Figura de Tijolos