Creative Lab — API de Fidget Colapsável

Transforme uma foto de origem em um brinquedo fidget colapsável pronto para impressão: a silhueta do sujeito se torna um conjunto de anéis concêntricos aninhados que colapsam de forma plana e se esticam novamente, impressos em uma única peça, sem necessidade de montagem.

POST /openapi/creative-lab/fidget-collapsible/v1

Diferente dos outros endpoints do Creative Lab, este não possui um par de estágios de protótipo/build — não há candidatos intermediários para escolher, então uma única tarefa carrega a imagem até chegar a um modelo 3D. Os controles de geometria que o aplicativo web expõe (tamanho, número de camadas, largura do vão, espessura de parede, profundidade de extrusão, abaulamento) também não fazem parte da requisição: toda tarefa é construída com os padrões definidos no lado do servidor.

POST/openapi/creative-lab/fidget-collapsible/v1

Criar uma Tarefa de Fidget Colapsável

Gere um modelo de fidget colapsável a partir de uma foto de origem. Consulte O Objeto de Tarefa de Fidget Colapsável para o formato da resposta.

Cada tarefa custa 6 créditos e requer um plano pago.

Parâmetros

Name
image_url
Type
string
Obrigatório
Description
Foto de origem para a Meshy transformar em um fidget colapsável. Atualmente suportamos os formatos .jpg, .jpeg, .png e .webp.
Há duas formas de fornecer a imagem:
- URL publicamente acessível: Uma URL que é acessível a partir da internet pública.
- Data URI: Um Data URI da imagem codificado em base64. Exemplo de um Data URI: data:image/jpeg;base64,<seus dados de imagem codificados em base64>.
Um assunto com um contorno único e fechado funciona melhor — a silhueta é o que se torna os anéis. Fundos com muitos elementos, vários assuntos separados ou formas muito finas podem deixar muito pouca área para as paredes aninhadas, e a tarefa falha com um erro de tarefa.
Name
name
Type
string
Description
Nome opcional da tarefa para fins de exibição. Máximo de 100 caracteres. Este é apenas um rótulo da tarefa; nada é gravado no modelo.

Retornos

A propriedade result da resposta contém o id da tarefa da tarefa de fidget colapsável recém-criada. Faça polling no endpoint Obter uma Tarefa ou inscreva-se no stream até que a tarefa alcance SUCCEEDED, então baixe o STL imprimível em model_urls.stl (e, quando presente, o GLB em model_urls.glb para pré-visualizá-lo primeiro).

Modos de Falha

Name
400 - Bad Request
Description
A requisição foi 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 suportado (.jpg, .jpeg, .png, .webp).
- Dimensões da imagem fora do intervalo: A imagem é muito pequena, 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álido: A string em base64 está malformada.
- Conteúdo sinalizado: A imagem de entrada foi sinalizada pela moderation de NSFW.
Name
401 - Unauthorized
Description
A autenticação falhou. Verifique sua chave de API.
Name
402 - Payment Required
Description
Ou sua conta está no plano gratuito — a criação de tarefas neste endpoint requer um plano pago — ou você tem créditos insuficientes.
Name
403 - Forbidden
Description
A imagem de entrada foi sinalizada por violação de propriedade intelectual.
Name
429 - Too Many Requests
Description
Você excedeu seu limite de taxa.

Request

POST

/openapi/creative-lab/fidget-collapsible/v1

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1 \
  -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"
}

GET/openapi/creative-lab/fidget-collapsible/v1/:id

Recuperar uma Tarefa de Fidget Retrátil

Recupera uma tarefa de fidget retrátil a partir de um id de tarefa válido. Apenas tarefas criadas através deste endpoint podem ser acessadas aqui — uma tarefa de outro endpoint do Creative Lab, ou uma criada no aplicativo web, retorna 404.

Consulte O Objeto de Tarefa de Fidget Retrátil para o formato da resposta.

Parâmetros

Name
id
Type
path
Description
Identificador único da tarefa de fidget retrátil a ser recuperada.

Retornos

A resposta contém o objeto de tarefa de fidget retrátil.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Excluir uma Tarefa de Fidget Colapsável

Cancela uma tarefa de fidget colapsável. 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 pode já estar consumindo recursos). Tarefas que já atingiram um estado terminal (SUCCEEDED, FAILED, CANCELED) não podem ser canceladas.

Parâmetros de Caminho

Name
id
Type
path
Description
Identificador único da tarefa de fidget colapsável a ser cancelada.

Retornos

Retorna 204 No Content em caso de sucesso, 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 não foi criada através deste endpoint.

Request

DELETE

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

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

GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

Transmitir uma Tarefa de Fidget Retrátil

Transmita atualizações em tempo real para uma tarefa de fidget retrátil via Server-Sent Events (SSE). Uma tarefa que não existe, ou que não foi criada através deste endpoint, emite um único payload event: error com status_code: 404 e encerra o stream.

Parâmetros

Name
id
Type
path
Description
Identificador único da tarefa de fidget retrátil a ser transmitida.

Retornos

Retorna um stream de objetos de tarefa Fidget Retrátil como Server-Sent Events. Para tarefas PENDING ou IN_PROGRESS, o stream de resposta incluirá apenas os campos progress e status necessários.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (task not found, or not created through this endpoint)
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": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

GET/openapi/creative-lab/fidget-collapsible/v1

Listar Tarefas de Fidget Colapsável

Recupera uma lista paginada das suas tarefas de fidget colapsável. Somente as tarefas criadas por meio deste endpoint são incluídas.

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 a ser usado para ordenação. Valores disponíveis:
- +created_at: Ordenar pelo horário de criação em ordem crescente.
- -created_at: Ordenar pelo horário de criação em ordem decrescente.

Retornos

Retorna uma lista paginada de o objeto de tarefa de fidget colapsável.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-fidget-collapsible",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123512000,
    "expires_at": 1729382712000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

O objeto Collapsible Fidget Task

O objeto Collapsible Fidget Task é uma unidade de trabalho que a Meshy monitora para transformar uma foto de origem em um modelo de fidget colapsável imprimível diretamente na impressora (print-in-place). É uma tarefa de estágio único: não há protótipo a partir do qual encadear, e a silhueta intermediária não faz parte da resposta.

Propriedades

Name
id
Type
string
Description
Identificador único da tarefa. Embora usemos um UUID k-sortable para os 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-fidget-collapsible.
Name
name
Type
string
Description
O nome da tarefa fornecido no momento da criação. String vazia caso nenhum nome tenha 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. Assim que a tarefa for concluída com sucesso, ela 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 foi iniciada, 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 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 (os créditos são reembolsados em caso de falha).
Name
model_urls
Type
object
Description
URLs para download do modelo 3D gerado. Preenchido assim que a tarefa atinge SUCCEEDED: stl está sempre presente, glb apenas quando a renderização de pré-visualização for bem-sucedida.
- Name
  stl
  Type
  string
  Description
  URL para download do arquivo STL. Este é o entregável imprimível — envie-o diretamente para um fatiador.
- Name
  glb
  Type
  string
  Description
  URL para download do arquivo GLB, para pré-visualizar o modelo em um visualizador 3D. Suas cores são apenas para pré-visualização: o STL não carrega cor, e um fidget impresso assume a cor do filamento. O GLB é fornecido em regime de melhor esforço: quando a renderização de pré-visualização não está disponível, a chave é omitida completamente de model_urls, então leia-a de forma defensiva — stl é o entregável e está sempre presente em uma tarefa SUCCEEDED.

Example Collapsible Fidget Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}