Creative Lab — API de Figura
Transforme uma foto de origem numa figura colecionável 3D em estilo chibi em duas etapas:
protótipo gera uma imagem de conceito estilizada a partir da sua foto de entrada, depois
construção transforma essa imagem de conceito num modelo 3D com textura. As duas etapas
estão ligadas através de input_task_id.
POST /openapi/creative-lab/figure/v1/prototypePOST /openapi/creative-lab/figure/v1/build
Criar uma Tarefa de Protótipo de Figura
Gere uma única imagem conceptual 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 construção. Consulte O Objeto de 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 suportamos os formatos
.jpg,.jpeg,.pnge.webp.Existem duas maneiras de fornecer a imagem:
- URL publicamente acessível: Um URL 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,<your base64-encoded image data>.
- Name
- name
- Type
- string
- Description
Nome opcional da tarefa para fins de exibição. Máximo de 100 caracteres.
- Name
- remove_background
- Type
- boolean
- predefinição false
- Description
Quando definido como
true, a imagem protótipo é retornada como um PNG RGBA transparente com o fundo removido, permitindo compor o sujeito em qualquer fundo.
Retornos
A propriedade result da resposta contém o ID da tarefa id da tarefa de protótipo de figura recém-criada. Consulte o endpoint Obter uma Tarefa ou subscreva o stream até que a tarefa atinja SUCCEEDED, depois passe esse ID para o endpoint de construção como input_task_id.
Modos de Falha
- Name
400 - Bad Request- Description
O pedido foi inaceitável. Causas comuns:
- Parâmetro em falta:
image_urlé obrigatório. - Formato de imagem inválido: O
image_urlfornecido não é um formato suportado (.jpg,.jpeg,.png,.webp). - Dimensões da imagem fora do intervalo: A imagem é demasiado pequena, excede o tamanho máximo do ficheiro ou excede o número máximo de píxeis.
- URL inacessível: O
image_urlnã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 por moderação NSFW ou de propriedade intelectual.
- Parâmetro em falta:
- 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
429 - Too Many Requests- Description
Excedeu o seu limite de taxa.
Pedido
# Stage 1: generate a chibi-style concept image
curl 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>"
}'
Resposta
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Criar uma Tarefa de Construção de Figura
Gere a figura 3D final texturizada 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, 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 para a forma de 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
SUCCEEDEDe deve ter produzido exatamente uma imagem candidata.Tarefas de protótipo criadas através da aplicação web não são aceites — o endpoint de construção aceita apenas tarefas de protótipo produzidas por
POST /openapi/creative-lab/figure/v1/prototypee recusa qualquer outra fonte com404.
- 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 da nova tarefa de construção de figura criada. Consulte o endpoint Obter uma Tarefa ou subscreva o stream até que a tarefa alcance 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 preferir OBJ).
Modos de Falha
- Name
400 - Bad Request- Description
O pedido foi inaceitável. Causas comuns:
- Parâmetro em falta:
input_task_idé obrigatório. - UUID inválido: O
input_task_idnão é um UUID válido. - Pai não bem-sucedido: A tarefa de protótipo referenciada ainda não alcançou
SUCCEEDED. - Sem candidato: A tarefa de protótipo foi bem-sucedida mas não produziu nenhuma imagem candidata.
- Parâmetro em falta:
- 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 aplicação web (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
# Stage 2: chain build off a succeeded prototype task
curl 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"
}'
Resposta
{
"result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}
Recuperar uma Tarefa de Figura
Recupere uma tarefa de protótipo ou construção dado um id de tarefa válido. O caminho do URL
deve corresponder à fase da tarefa — uma tarefa de construção obtida através de
/prototype/:id retorna 404, e vice-versa.
Consulte O Objeto de Tarefa de Protótipo de Figura e O Objeto de Tarefa de Construção de Figura para formatos de resposta.
Parâmetros
- Name
- id
- Type
- path
- Description
Identificador único para a tarefa de figura a recuperar.
Retorna
A resposta contém o objeto da tarefa de figura. O formato depende de qual fase foi solicitada.
Pedido
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# Build
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Resposta do Protótipo
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "creative-lab-figure-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123456000,
"started_at": 1729123460000,
"finished_at": 1729123486000,
"expires_at": 1729382686000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
Resposta da Construção
{
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"type": "creative-lab-figure-build",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123500000,
"started_at": 1729123510000,
"finished_at": 1729123535000,
"expires_at": 1729382735000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20,
"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=***"
}
]
}
Eliminar uma Tarefa de Figura
Cancelar uma tarefa de figura. 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). As tarefas que já atingiram um estado terminal (SUCCEEDED, FAILED, CANCELED) não podem ser canceladas.
O caminho do URL deve corresponder à fase da tarefa — DELETE em
/prototype/:buildId retorna 404.
Parâmetros de Caminho
- Name
- id
- Type
- path
- Description
Identificador único para a tarefa de figura 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 a sua fase não corresponde ao caminho do URL.
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
// Returns 204 No Content on success (empty body).
Transmitir uma Tarefa de Figura
Transmitir atualizações em tempo real para uma tarefa de figura via Server-Sent Events (SSE).
O caminho do URL deve corresponder à fase da tarefa — abrir uma transmissão em
/prototype/:buildId/stream emite um único event: error payload com
status_code: 404 e fecha a transmissão.
Parâmetros
- Name
- id
- Type
- path
- Description
Identificador único para a tarefa de figura a transmitir.
Retornos
Retorna uma transmissão de objetos de tarefa Figura Protótipo
ou Figura Construída como Server-Sent Events. Para tarefas PENDING ou IN_PROGRESS, a transmissão de resposta incluirá apenas os campos necessários progress e status.
Pedido
curl -N https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Transmissão de Resposta
// Error event example (wrong stage or task not found)
event: error
data: {
"status_code": 404,
"message": "Task not found"
}
// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"type": "creative-lab-figure-build",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123500000,
"started_at": 1729123510000,
"finished_at": 1729123535000,
"expires_at": 1729382735000,
"task_error": null,
"consumed_credits": 20,
"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=***"
}
]
}
Listar Tarefas de Figura
Obtenha uma lista paginada das suas tarefas de figura 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 do outro estágio não são incluídas em nenhuma das respostas.
Parâmetros de Caminho
- Name
- stage
- Type
- path
- Obrigatório
- Description
Ou
prototypeoubuild. A coleção retorna apenas tarefas cujo estágio corresponde à URL — buscar/prototypenunca 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 de tamanho da página. O máximo permitido é
50itens.
- 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 ascendente.-created_at: Ordenar por tempo de criação em ordem descendente.
Retornos
Retorna uma lista paginada do objeto de tarefa por estágio — ou
o objeto de tarefa de protótipo de figura
ao listar /prototype ou
o objeto de tarefa de construção de figura ao
listar /build.
Pedido
# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Resposta (Listar Tarefas de Protótipo)
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "creative-lab-figure-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123456000,
"started_at": 1729123460000,
"finished_at": 1729123486000,
"expires_at": 1729382686000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
]
O Objeto Tarefa de Protótipo de Figura
O objeto Tarefa de Protótipo de Figura é uma unidade de trabalho que a Meshy acompanha para gerar uma imagem conceptual em estilo chibi a partir de uma foto de origem. O resultado desta fase é encadeado na fase de construção através de input_task_id.
Propriedades
- Name
- id
- Type
- string
- Description
Identificador único para a tarefa. Embora usemos um UUID ordenável por k para os ids de tarefa como detalhe de implementação, não deve fazer quaisquer suposições 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 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 tenha sido 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. 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á
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 foi 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 precedentes.
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_PROGRESSouSUCCEEDED. Retorna0para tarefasFAILED(os créditos são reembolsados em caso de falha).
- Name
- image_urls
- Type
- array of strings
- Description
URLs descarregáveis para os candidatos a imagem conceptual gerados por esta tarefa de 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 alteração disruptiva.
Exemplo de Objeto Tarefa de Protótipo de Figura
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "creative-lab-figure-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123456000,
"started_at": 1729123460000,
"finished_at": 1729123486000,
"expires_at": 1729382686000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
O Objeto de Tarefa de Construção de Figura
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 único para a 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
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, isto 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
0para tarefasFAILED(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 compartilhada
V2ImageTo3DTaskResponseusada 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 da figura emite um GLB texturizado mais o par OBJ + MTL para pipelines que preferem Wavefront OBJ. A forma do campo corresponde ao objeto Image to 3D model_urls para que futuras adições de formato se encaixem sem uma alteração 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. Emparelhe com
obje a entrada detexture_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 de 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
{
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"type": "creative-lab-figure-build",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123500000,
"started_at": 1729123510000,
"finished_at": 1729123535000,
"expires_at": 1729382735000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20,
"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=***"
}
]
}