Creative Lab — API do Fidget Colapsável

Transforme uma foto de origem em um brinquedo fidget colapsável para impressão em peça única: a silhueta do assunto se torna um conjunto de anéis concêntricos aninhados que se 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 task leva a imagem até o modelo 3D. Os controles de geometria que o aplicativo web expõe (tamanho, número de camadas, largura do espaçamento, espessura de parede, profundidade de extrusão, abaulamento) também não fazem parte da requisição: todas as tasks são construídas com os mesmos valores padrão definidos no servidor.

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

Criar uma Tarefa de Fidget Colapsável

Gera 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 maneiras 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 claramente fechado funciona melhor — a silhueta é o que se transforma nos anéis. Fundos cheios de 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 de tarefa opcional para fins de exibição. Máximo de 100 caracteres. Isso é apenas um rótulo de tarefa; nada é gravado no modelo.

Retornos

A propriedade result da resposta contém o id de tarefa da tarefa de fidget colapsável recém-criada. Consulte periodicamente o endpoint Obter uma Tarefa ou inscreva-se no stream até que a tarefa atinja 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 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 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 base64 está malformada.
- Conteúdo sinalizado: A imagem de entrada foi sinalizada pela moderation de NSFW.
Name
401 - Unauthorized
Description
Falha na autenticação. Por favor, 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 Colapsável

Recupere uma tarefa de fidget colapsável a partir de um id de tarefa válido. Apenas tarefas criadas por meio deste endpoint são acessíveis aqui — uma tarefa de outro endpoint do Creative Lab, ou uma criada no aplicativo web, retorna 404.

Consulte O Objeto de Tarefa de Fidget Colapsável para o formato da resposta.

Parâmetros

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

Retornos

A resposta contém o objeto de tarefa de fidget colapsável.

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 por meio 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 Colapsível

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

Parâmetros

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

Retornos

Retorna um stream de objetos de tarefa Collapsible Fidget como Server-Sent Events. Cada frame carrega o objeto de tarefa completo do estágio — o mesmo formato que o endpoint Get retorna — então, enquanto a tarefa está PENDING ou IN_PROGRESS, os campos de saída simplesmente ainda não estão preenchidos (null, [] ou {}) e finished_at é null.

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.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
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

Recupere uma lista paginada das suas tarefas de fidget colapsível. Apenas as tarefas criadas através 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 para ordenação. Valores disponíveis:
- +created_at: Ordena pelo horário de criação em ordem crescente.
- -created_at: Ordena pelo horário de criação em ordem decrescente.

Retornos

Retorna uma lista paginada de objetos 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 para impressão direta. É uma tarefa de estágio único: não há protótipo 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 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 da tarefa. O valor é creative-lab-fidget-collapsible.
Name
name
Type
string
Description
O nome da tarefa fornecido na criação da tarefa. 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, essa propriedade será 0. Assim que 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 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, essa 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, essa 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 de 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 obtém sua cor a partir do filamento. O GLB é gerado em regime de melhor esforço: quando a renderização de pré-visualização não está disponível, a chave é omitida inteiramente 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=***"
  }
}