Transforme uma foto de origem em uma figura 3D colecionável em estilo chibi em duas etapas:
protótipo gera uma imagem de conceito estilizada a partir da sua foto de entrada; em seguida,
construção transforma essa imagem de conceito em um modelo 3D com textura. As duas etapas
são vinculadas por meio de input_task_id.
Gere uma única imagem conceitual em estilo chibi a partir da foto de origem. O
ID da tarefa retornado é o que você passa como input_task_id para o
endpoint de build. Consulte
O objeto da tarefa de protótipo de figura
para o formato da resposta.
Parâmetros
Name
image_url
Type
string
Obrigatório
Description
Foto de origem para a Meshy estilizar como uma figura chibi. Atualmente oferecemos suporte aos formatos .jpg, .jpeg, .png e .webp.
Há duas maneiras de fornecer a imagem:
URL acessível publicamente: uma URL que pode ser acessada pela internet pública.
Data URI: um Data URI da imagem codificado em base64. Exemplo de Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
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 tarefa de protótipo de figura recém-criada. Consulte periodicamente o endpoint Obter uma tarefa ou assine o stream até que a tarefa atinja SUCCEEDED; em seguida, passe esse ID para o endpoint de build como input_task_id.
Modos de falha
Name
400 - Bad Request
Description
A solicitação era 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 compatível (.jpg, .jpeg, .png, .webp).
Dimensões da imagem fora do intervalo: a imagem é pequena demais, excede o tamanho máximo de arquivo ou excede a contagem máxima de pixels.
URL inacessível: não foi possível baixar o image_url (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.
Name
401 - Unauthorized
Description
A autenticação falhou. Verifique sua chave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para executar esta tarefa.
Name
429 - Too Many Requests
Description
Você excedeu seu limite de taxa.
Request
POST
/openapi/creative-lab/figure/v1/prototype
# Stage 1: generate a chibi-style concept imagecurl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype \ -X POST \ -H "Authorization: Bearer ${YOUR_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ "image_url": "<your publicly accessible image url or base64-encoded data URI>" }'
Response
{"result":"018a210d-8ba4-705c-b111-1f1776f7f578"}
Prototype example
Start with a source portrait, then generate the prototype image used by the build stage.
Gere a figura 3D final com textura a partir de uma tarefa de protótipo bem-sucedida.
O build 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 da tarefa de build de figura para ver a
estrutura da resposta.
Parâmetros
Name
input_task_id
Type
string
Obrigatório
Description
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 alcançado SUCCEEDED e deve ter produzido exatamente uma imagem candidata.
Tarefas de protótipo criadas pelo 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.
Name
name
Type
string
Description
Nome opcional da tarefa para fins de exibição. Máximo de 100 caracteres.
Retorna
A propriedade result da resposta contém o id da tarefa de build de figura recém-criada. Consulte o endpoint Obter uma tarefa ou assine o stream até que a tarefa alcance SUCCEEDED; em seguida, baixe o GLB com textura em model_urls.glb (ou o par OBJ + MTL em model_urls.obj e model_urls.mtl se seu pipeline posterior preferir OBJ).
Modos de falha
Name
400 - Bad Request
Description
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.
Pai não bem-sucedido: A tarefa de protótipo referenciada ainda não alcançou SUCCEEDED.
Nenhum candidato: A tarefa de protótipo foi bem-sucedida, mas não produziu nenhuma imagem candidata.
Name
401 - Unauthorized
Description
A autenticação falhou. 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 pelo webapp (somente tarefas de protótipo em mode de API são encadeadas para o build).
Name
429 - Too Many Requests
Description
Você excedeu seu limite de taxa.
Request
POST
/openapi/creative-lab/figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurl https://api.meshy.ai/openapi/creative-lab/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" }'
Response
{"result":"019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"}
Build example
The build task turns the selected prototype image into a downloadable textured 3D model.
Recupere uma tarefa de protótipo ou build usando um id de tarefa válido. O caminho da URL
deve corresponder à etapa da tarefa — uma tarefa de build obtida por meio de
/prototype/:id retorna 404, e vice-versa.
Cancela uma tarefa de figura. Se a tarefa ainda estiver PENDING, os créditos
consumidos no momento da criação serão reembolsados. Tarefas que já estão
IN_PROGRESS são canceladas sem reembolso (o worker já pode estar
consumindo Recursos). Tarefas que já atingiram 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 da tarefa de figura a ser cancelada.
Retornos
Retorna 204 No Content em caso de sucesso com um corpo vazio.
Modes 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 outro usuário ou seu estágio não corresponde ao caminho da URL.
Transmita atualizações em tempo real para uma tarefa de figura via Server-Sent Events (SSE).
O caminho da URL deve corresponder à etapa da tarefa — abrir um fluxo em
/prototype/:buildId/stream emite um único payload event: error com
status_code: 404 e fecha o fluxo.
Parâmetros
Name
id
Type
path
Description
Identificador único da tarefa de figura a ser transmitida.
Retorno
Retorna um fluxo de objetos de tarefa de Protótipo de figura
ou Build de figura como
Server-Sent Events. Para tarefas PENDING ou IN_PROGRESS, o fluxo de
resposta incluirá apenas os campos necessários progress e status.
Recupere uma lista paginada das suas tarefas de figura para uma única etapa. O caminho
da URL seleciona a etapa — /prototype retorna tarefas de protótipo; /build
retorna tarefas de build. Tarefas da outra etapa não são incluídas em nenhuma das
respostas.
Parâmetros de caminho
Name
stage
Type
path
Obrigatório
Description
prototype ou build. A coleção retorna apenas tarefas
cuja etapa corresponde à URL — buscar /prototype nunca retorna
tarefas de build 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 é 50 itens.
Name
sort_by
Type
string
padrão -created_at
Description
Campo pelo qual ordenar. Valores disponíveis:
+created_at: Ordenar por hora de criação em ordem crescente.
-created_at: Ordenar por hora de criação em ordem decrescente.
O objeto de tarefa de protótipo de figura é uma unidade de trabalho que a Meshy acompanha para
gerar uma imagem conceitual no estilo chibi a partir de uma foto de origem. A saída
desta etapa é encadeada para a etapa de construção
via input_task_id.
Propriedades
Name
id
Type
string
Description
Identificador exclusivo da tarefa. Embora usemos um UUID k-sortable para ids de tarefas como detalhe de implementação, você não deve fazer nenhuma suposição sobre o formato do id.
Name
type
Type
string
Description
Tipo da tarefa. O valor é creative-lab-figure-prototype.
Name
name
Type
string
Description
O nome da tarefa fornecido quando a tarefa foi criada. String vazia se nenhum nome tiver sido 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
progress da tarefa. Se a tarefa ainda não tiver sido iniciada, esta propriedade será 0. Depois que a tarefa for concluída com sucesso, 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. 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 sido iniciada, esta propriedade será 0.
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 tiver sido concluída, esta propriedade será 0.
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 só é significativo se o status da tarefa for PENDING.
Name
task_error
Type
object
Description
Detalhes do erro para tarefas com falha. Consulte 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 das candidatas a imagem conceitual geradas por esta tarefa de protótipo. Atualmente, a API sempre retorna exatamente uma candidata; o campo é um array para que revisões futuras possam apresentar várias candidatas sem uma alteração incompatível.
O objeto de tarefa de construção de figura é uma unidade de trabalho que a Meshy acompanha para
gerar uma figura 3D texturizada a partir de uma tarefa de protótipo bem-sucedida. Ele
executa o mesmo pipeline de Imagem para 3D usado por Imagem para 3D,
portanto, os campos de saída espelham o objeto de tarefa desse endpoint.
Propriedades
Name
id
Type
string
Description
Identificador exclusivo da tarefa.
Name
type
Type
string
Description
Tipo da tarefa. O valor é creative-lab-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. Os valores possíveis são um de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress da tarefa. Se a tarefa ainda não foi iniciada, esta propriedade será 0. Quando a tarefa for 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 com falha. Consulte 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 o formato compartilhado V2ImageTo3DTaskResponse usado 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 para download do modelo 3D gerado. A construção de figura emite um GLB texturizado, além do par OBJ + MTL para pipelines que preferem Wavefront OBJ. O formato do campo corresponde ao objeto model_urls de Imagem para 3D, para que futuras adições de formato se encaixem sem uma alteração incompatível.
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 complementar do OBJ. Combine com obj e a entrada de texture_urls[0].base_color.
Name
thumbnail_url
Type
string
Description
URL para download da imagem de miniatura do arquivo do modelo.
Name
texture_urls
Type
array
Description
Um array de objetos de URL de textura gerados por esta tarefa. Atualmente contém um único objeto com o mapa de cor base.