Transforme uma foto de origem numa minifigura colecionável em estilo de tijolo em duas fases:
protótipo gera uma imagem conceptual estilizada a partir da sua foto de entrada, depois
construir transforma essa imagem conceptual num modelo 3D com texturas. As duas fases
estão ligadas através do input_task_id.
POST /openapi/creative-lab/brick-figure/v1/prototype
Gere uma única imagem conceptual em estilo brick a partir da foto de origem. O identificador da tarefa devolvido é o que você passa como input_task_id para o endpoint de construção. Consulte o O Objeto de Tarefa de Protótipo de Figura de Brick para a forma da resposta.
Parâmetros
Name
image_url
Type
string
Obrigatório
Description
Foto de origem para o Meshy estilizar como uma minifigura de brick. Atualmente suportamos os formatos .jpg, .jpeg, .png e .webp.
Existem duas maneiras de fornecer a imagem:
URL Publicamente acessível: Um URL que é acessível a partir 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 opcional da tarefa para fins de exibição. Máximo de 100 caracteres.
Devolve
A propriedade result da resposta contém o id da tarefa recém-criada do protótipo de figura de brick. Consulte o endpoint Obter uma Tarefa ou subscreva o stream até que a tarefa atinja 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 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 de imagem fora do limite: A imagem é muito pequena, excede o tamanho máximo do ficheiro ou excede o número máximo de píxeis.
URL inacessível: O image_url não pôde ser descarregado (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 propriedade intelectual.
Name
401 - Unauthorized
Description
A autenticação falhou. Por favor, verifique a 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
Excedeu o seu limite de taxa.
Pedido
POST
/openapi/creative-lab/brick-figure/v1/prototype
# Etapa 1: gerar uma imagem conceptual em estilo brickcurl 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 tijolos em 3D com textura a partir de uma tarefa de protótipo bem-sucedida.
A construção executa o mesmo pipeline de imagem-para-3D como
Imagem para 3D, por isso o formato do objeto de resposta e a
lista de URLs de saída coincidem exatamente. Consulte
O Objeto da Tarefa de Construção de Figura de Tijolos para o
formato da resposta.
Parâmetros
Name
input_task_id
Type
string
Obrigatório
Description
O ID da tarefa de um protótipo criado 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 através da 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 fonte 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 figura de tijolos recém-criada. Consulte o endpoint Obter uma Tarefa ou subscreva ao stream até que a tarefa chegue a SUCCEEDED, depois descarregue o GLB texturizado de model_urls.glb (ou o par OBJ + MTL de model_urls.obj e model_urls.mtl se o seu pipeline de downstream preferir OBJ).
Modos de Falha
Name
400 - Bad Request
Description
O pedido foi inaceitável. Causas comuns:
Parâmetro em falta: input_task_id é necessá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 candidato: A tarefa de protótipo foi bem-sucedida, mas não produziu nenhuma imagem candidata.
Name
401 - Unauthorized
Description
A autenticação falhou. Por favor, verifique a sua chave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarefa.
Name
404 - Not Found
Description
A tarefa de protótipo referenciada não existe, pertence a um utilizador diferente, ou foi criada através da webapp (apenas tarefas de protótipo em modo API encadeiam na construção).
Name
429 - Too Many Requests
Description
Excedeu o seu limite de taxa.
Pedido
POST
/openapi/creative-lab/brick-figure/v1/build
# Etapa 2: construir cadeia 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 dado um id de tarefa válido. O caminho
do URL deve corresponder à etapa da tarefa — uma tarefa de construção
recuperada através de /prototype/:id retorna 404, e vice-versa.
Cancelar uma tarefa de figura de tijolos. Se a tarefa ainda estiver PENDING, os créditos consumidos no momento da criação são reembolsados. As tarefas que já estão IN_PROGRESS são canceladas sem reembolso (o trabalhador pode já estar a consumir recursos). Tarefas que já atingiram um estado terminal (SUCCEEDED, FAILED, CANCELED) não podem ser canceladas.
O caminho do URL deve corresponder ao estágio da tarefa — DELETE em
/prototype/:buildId devolve 404.
Parâmetros do Caminho
Name
id
Type
path
Description
Identificador único para a tarefa de figura de tijolos a cancelar.
Retornos
Retorna 204 No Content em caso de sucesso, com um corpo vazio.
Modos de Falha
Name
400 - Bad Request
Description
A tarefa já está num estado terminal e não pode ser cancelada.
Name
404 - Not Found
Description
A tarefa não existe, pertence a um utilizador diferente ou o seu estágio não corresponde ao caminho do URL.
Transmite atualizações em tempo real para uma tarefa de figura através de Server-Sent Events (SSE).
O caminho da URL deve corresponder ao estágio da tarefa — abrir um fluxo em
/prototype/:buildId/stream emite uma única event: error payload com
status_code: 404 e fecha o fluxo.
Parâmetros
Name
id
Type
path
Description
Identificador único para a tarefa de figura a ser transmitida.
Retornos
Retorna um fluxo de objetos de tarefa de Figura Protótipo
ou Figura Construída 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 evento 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=***" } ]}
Recuperar uma lista paginada das suas tarefas de figura para uma única fase.
O caminho da URL seleciona a fase — /prototype retorna tarefas de protótipo; /build
retorna tarefas de construção. As tarefas da outra fase não são incluídas em
nenhuma das respostas.
Parâmetros de Caminho
Name
stage
Type
path
Obrigatório
Description
Ou prototype ou build. A coleção retorna apenas tarefas
cuja fase corresponde à URL — buscar /prototype nunca retorna
tarefas de construção e vice-versa.
Parâmetros de Consulta
Name
page_num
Type
integer
predefinição 1
Description
Número da página para paginação.
Name
page_size
Type
integer
predefinição 10
Description
Limite do tamanho da página. O máximo permitido é 100 itens.
Name
sort_by
Type
string
predefinição -created_at
Description
Campo para ordenar. Valores disponíveis:
+created_at: Ordenar por tempo de criação em ordem crescente.
-created_at: Ordenar por tempo de criação em ordem decrescente.
O objeto Tarefa de Protótipo de Figura de Tijolos é uma unidade de trabalho que a Meshy mantém o registo para gerar uma imagem conceito em estilo de tijolo a partir de uma foto de origem. A saída desta etapa é encadeada na etapa de construção através de input_task_id.
Propriedades
Name
id
Type
string
Description
Identificador único para a tarefa. Embora usemos um UUID k-ordenável 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 de tarefa. O valor é creative-lab-brick-figure-prototype.
Name
name
Type
string
Description
O nome da tarefa fornecido quando a tarefa foi criada. Cadeia vazia se nenhum nome foi fornecido.
Name
status
Type
string
Description
Estado 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 for bem-sucedida, isto 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, 12:00:00 PM GMT é representado como 1693569600000. Isto aplica-se
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 foi iniciada, esta propriedade será null.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi concluída, em milissegundos. Se a tarefa ainda não estiver concluída, 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 anteriores.
O valor deste campo é significativo apenas se o estado da tarefa for PENDING.
Name
task_error
Type
object
Description
Detalhes do erro para tarefas falhadas. 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 estado da tarefa é PENDING, IN_PROGRESS, ou SUCCEEDED. Retorna 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).
Name
image_urls
Type
array of strings
Description
URLs descarregáveis para os candidatos de imagem conceptual gerados por esta tarefa protótipo. Atualmente a API retorna sempre exatamente um candidato; o campo é um array para que futuras revisões possam apresentar vários candidatos sem uma alteração de quebra.
O Objeto Tarefa de Construção de Figura de Tijolos é uma unidade de trabalho que a Meshy monitora para gerar uma figura de tijolos 3D texturizada a partir de uma tarefa de protótipo SUCCEEDED. Ele executa o mesmo pipeline de imagem-para-3D usado por Imagem para 3D, de modo que os campos de saída espelham o objeto de tarefa desse 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. String vazia se nenhum nome foi fornecido.
Name
status
Type
string
Description
Status da tarefa. Valores possíveis são um dos 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 concluída, 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 apenas quando o status é PENDING.
Name
task_error
Type
object
Description
Detalhes do erro para tarefas falhadas. 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. Retorna 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).
Name
prompt
Type
string
Description
Sempre vazio para construção de figura. Presente para compatibilidade entre endpoints com a forma partilhada V2ImageTo3DTaskResponse utilizada por Imagem para 3D.
Name
negative_prompt
Type
string
Description
Sempre vazio para construção de figura. Presente para compatibilidade entre endpoints.
Name
texture_prompt
Type
string
Description
Sempre vazio para construção de figura. Presente para compatibilidade entre endpoints.
Name
texture_image_url
Type
string
Description
Sempre vazio para construção de figura. Presente para compatibilidade entre endpoints.
Name
model_urls
Type
object
Description
URLs disponíveis para download para o modelo 3D gerado. A construção de figura emite um GLB texturizado mais o par OBJ + MTL para pipelines que preferem Wavefront OBJ. A forma do campo corresponde ao objeto Imagem para 3D model_urls para que futuras adições de formato possam ser encaixadas sem uma mudança radical.
Name
glb
Type
string
Description
URL disponível para download para o ficheiro GLB texturizado.
Name
obj
Type
string
Description
URL disponível para download para o ficheiro Wavefront OBJ (geometria + UV).
Name
mtl
Type
string
Description
URL disponível para download para o ficheiro material OBJ companheiro MTL. Utilize com obj e a entrada de texture_urls[0].base_color.
Name
thumbnail_url
Type
string
Description
URL disponível para download da imagem em miniatura do ficheiro do modelo.
Name
texture_urls
Type
array
Description
Um array de objetos de URLs 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 disponível para download da imagem do mapa de cor base.
Exemplo de Objeto de Tarefa de Construção de Figura