Creative Lab — API de chaveiro

Transforme uma foto de origem em um medalhão de chaveiro imprimível em 3D — um relevo de profundidade colorizado em formato de distintivo — em duas etapas: protótipo gera uma imagem conceitual colorizada a partir da sua foto de entrada; depois, build transforma essa imagem conceitual em um modelo 3D em relevo. As duas etapas são vinculadas por meio de input_task_id.

POST /openapi/creative-lab/keychain/v1/prototype
POST /openapi/creative-lab/keychain/v1/build

POST/openapi/creative-lab/keychain/v1/prototype

Criar uma tarefa de protótipo de chaveiro

Gere uma única imagem conceitual colorizada 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 chaveiro para o formato da resposta.

Parâmetros

Name
image_url
Type
string
Obrigatório
Description
Foto de origem para a Meshy colorizar em uma imagem conceitual pronta para chaveiro. Atualmente oferecemos suporte aos formatos .jpg, .jpeg, .png e .webp.
Há duas maneiras de fornecer a imagem:
- URL acessível publicamente: Uma URL acessível pela internet pública.
- Data URI: Uma Data URI da imagem codificada em base64. Exemplo de uma 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.

Retorna

A propriedade result da resposta contém o id da tarefa de protótipo de chaveiro recém-criada. Consulte o endpoint Obter uma tarefa ou assine o stream até que a tarefa alcance 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 não foi aceita. Causas comuns:
- Parâmetro ausente: image_url é obrigatório.
- Formato de imagem inválido: O image_url fornecido não é 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: O image_url não pôde ser baixado (404 ou timeout).
- Data URI inválida: A string base64 está malformada.
- Conteúdo sinalizado: A imagem de entrada foi sinalizada por moderation de NSFW ou propriedade intelectual.
Name
401 - Unauthorized
Description
Falha na autenticação. 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/keychain/v1/prototype

# Stage 1: generate a colorized keychain concept image
curl https://api.meshy.ai/openapi/creative-lab/keychain/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 photo, then generate the prototype image used by the keychain build stage.

Foto de origem usada como entrada do chaveiro do Creative Lab — Prototype input

Saída do protótipo de chaveiro do Creative Lab gerada a partir da foto de origem — Prototype output

POST/openapi/creative-lab/keychain/v1/build

Criar uma tarefa de build de chaveiro

Gere o medalhão de chaveiro final imprimível em 3D a partir de uma tarefa de protótipo bem-sucedida. O build executa um pipeline de relevo por mapa de profundidade na imagem conceitual colorizada do protótipo e entrega um único artefato de malha no formato que você solicitar. Consulte O objeto da tarefa de build de chaveiro para ver o formato 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/keychain/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.

`options`

Parâmetros opcionais de ajuste para a geometria do relevo. Cada campo tem um padrão adequado — envie apenas aqueles que você deseja substituir.

Name
badge_shape
Type
string
padrão circle
Description
Silhueta do contorno do medalhão de chaveiro. Valores disponíveis:
- circle (padrão)
- rounded-rect
- hexagon
- shield
- star
Name
size_mm
Type
number
padrão 40
Description
Comprimento da aresta do quadrado delimitador do chaveiro, em milímetros. Intervalo: (0, 400].
Name
relief_height_mm
Type
number
padrão 2.2
Description
Altura máxima do relevo acima da base, em milímetros. Intervalo: [0, 20].
Name
relief_offset_mm
Type
number
padrão 0
Description
Deslocamento vertical aplicado ao relevo antes da extrusão, em milímetros. Intervalo: [0, 20].
Name
base_thickness_mm
Type
number
padrão 0.1
Description
Espessura da placa base plana atrás do relevo, em milímetros. Intervalo: [0, 20].
Name
has_closed_back
Type
boolean
padrão true
Description
Indica se a parte traseira do medalhão é vedada como uma superfície fechada. Defina como false para uma casca aberta.
Name
relief_curve
Type
string
padrão linear
Description
Curva de transferência que mapeia valores do mapa de profundidade para a altura do relevo. Valores disponíveis:
- linear (padrão)
- gamma
- s-curve
Name
curve_param
Type
number
padrão 1.0
Description
Parâmetro de forma para a curva de transferência (significativo apenas quando relief_curve é gamma). Intervalo: (0, 10].
Name
invert_depth
Type
boolean
padrão false
Description
Inverta a interpretação do mapa de profundidade para que regiões mais escuras se tornem relevos mais altos.
Name
smoothing
Type
number
padrão 0.24
Description
Intensidade de suavização aplicada ao mapa de profundidade antes da extração do relevo. Intervalo: [0, 10].
Name
relief_scale
Type
number
padrão 1.0
Description
Multiplicador de escala vertical aplicado sobre relief_height_mm. Intervalo: (0, 10].
Name
depth_threshold
Type
number
padrão 0.1
Description
Limiar passa-baixa para valores do mapa de profundidade; tudo abaixo disso é limitado a zero. Intervalo: [0, 1].
Name
remove_background
Type
boolean
padrão true
Description
Remova automaticamente o fundo da imagem conceitual do protótipo antes de aplicar o relevo.
Name
export_resolution
Type
integer
padrão 512
Description
Resolução da malha usada para exportação. Intervalo: [64, 2048].

`output`

Seletor opcional de formato de transmissão. O padrão é glb.

Name
format
Type
string
padrão glb
Description
Pacote de artefato retornado pelo build. Valores disponíveis:
- glb (padrão) — retorna um único model.glb em model_urls.glb.
- obj — compacta model.obj + model.mtl + texture.png e retorna o pacote em model_urls.obj.
- zip — compacta todos os artefatos que o gerador emite e retorna o pacote em model_urls.bundle_zip.

Retorna

A propriedade result da resposta contém o id da tarefa de build de chaveiro recém-criada. Consulte o endpoint Obter uma tarefa ou assine o stream até que a tarefa alcance SUCCEEDED; em seguida, baixe o artefato a partir da única entrada em model_urls.

Modos de falha

Name
400 - Bad Request
Description
A solicitação não foi aceitá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.
- Opções fora do intervalo: Um dos campos de options ficou fora do intervalo permitido ou do conjunto de enumeração.
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 (apenas tarefas de protótipo em modo API encadeiam para build).
Name
429 - Too Many Requests
Description
Você excedeu seu limite de taxa.

Request

POST

/openapi/creative-lab/keychain/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "options": {
      "badge_shape": "circle",
      "size_mm": 40,
      "relief_height_mm": 2.5
    },
    "output": {
      "format": "glb"
    }
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}

Build example

The build task converts the selected prototype image into a 3D-printable keychain model.

Creative Lab Keychain build model preview — Build model preview

GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id

Recuperar uma tarefa de chaveiro

Recupere uma tarefa de protótipo ou build dado um id de tarefa válido. O caminho da URL deve corresponder à etapa da tarefa — uma tarefa de build buscada por meio de /prototype/:id retorna 404, e vice-versa.

Consulte O objeto de tarefa de protótipo de chaveiro e O objeto de tarefa de build de chaveiro para os formatos de resposta.

Parâmetros

Name
id
Type
path
Description
Identificador único da tarefa de chaveiro a recuperar.

Retorna

A resposta contém o objeto da tarefa de chaveiro. O formato depende de qual etapa foi solicitada.

Request

GET

/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-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=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-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,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

DELETE/openapi/creative-lab/keychain/v1/(prototype|build)/:id

Excluir uma tarefa de chaveiro

Cancela uma tarefa de chaveiro. 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 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 chaveiro a ser cancelada.

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á 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.

Request

DELETE

/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id/stream

Transmitir uma tarefa de chaveiro

Transmita atualizações em tempo real de uma tarefa de chaveiro via Server-Sent Events (SSE). O caminho da URL deve corresponder ao estágio da tarefa — abrir um stream em /prototype/:buildId/stream emite uma única payload event: error com status_code: 404 e fecha o stream.

Parâmetros

Name
id
Type
path
Description
Identificador único da tarefa de chaveiro a ser transmitida.

Retornos

Retorna um stream de objetos de tarefa de Protótipo de chaveiro ou Build de chaveiro como Server-Sent Events. Para tarefas PENDING ou IN_PROGRESS, o stream de resposta incluirá apenas os campos necessários progress e status.

Request

GET

/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

curl -N https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// 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-keychain-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

GET/openapi/creative-lab/keychain/v1/(prototype|build)

Listar tarefas de chaveiro

Recupere uma lista paginada das suas tarefas de chaveiro para um único estágio. O caminho da URL seleciona o estágio — /prototype retorna tarefas de protótipo; /build retorna tarefas de build. As tarefas do outro estágio não são incluídas em nenhuma resposta.

Parâmetros de caminho

Name
stage
Type
path
Obrigatório
Description
prototype ou build. A coleção retorna apenas tarefas cujo estágio 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 é de 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.

Retorna

Retorna uma lista paginada do objeto de tarefa por estágio — seja o objeto de tarefa de protótipo de chaveiro ao listar /prototype ou o objeto de tarefa de build de chaveiro ao listar /build.

Request

GET

/openapi/creative-lab/keychain/v1/prototype

# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-keychain-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 da tarefa de protótipo de chaveiro

O objeto da tarefa de protótipo de chaveiro é uma unidade de trabalho que a Meshy acompanha para gerar uma imagem conceitual colorizada a partir de uma foto de origem. A saída deste estágio é encadeada para o estágio 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 tarefa 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-keychain-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 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.
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 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 foi iniciada, esta propriedade será 0.
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á 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 é significativo apenas 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 (os 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 disponibilizar múltiplas candidatas sem uma alteração incompatível.

Example Keychain Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-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 chaveiro

O objeto de tarefa de construção de chaveiro é uma unidade de trabalho que a Meshy acompanha para gerar a malha 3D final do chaveiro a partir de uma tarefa de protótipo SUCCEEDED. A construção executa um pipeline de relevo por mapa de profundidade na imagem conceitual do protótipo e publica um único artefato de malha no formato solicitado pelo chamador.

Propriedades

Name
id
Type
string
Description
Identificador exclusivo da tarefa.
Name
type
Type
string
Description
Tipo da tarefa. O valor é creative-lab-keychain-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 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 anteriores. Significativa 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
model_urls
Type
object
Description
URLs para download do artefato gerado, indexadas pelo nome do artefato. Sempre contém exatamente uma entrada — o formato solicitado por meio do output.format da solicitação de build. A chave corresponde ao formato solicitado:
- Name
  glb
  Type
  string
  Description
  URL para download do arquivo GLB. Presente quando output.format era glb (o padrão).
- Name
  obj
  Type
  string
  Description
  URL para download de um pacote zip contendo model.obj, model.mtl e texture.png. Presente quando output.format era obj.
- Name
  bundle_zip
  Type
  string
  Description
  URL para download de um pacote zip de todos os artefatos que o gerador emite. Presente quando output.format era zip.

Example Keychain Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-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,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}