Creative Lab — API de Fidget Colapsável

Transforma uma foto de origem num brinquedo fidget colapsável para impressão direta: a silhueta do sujeito transforma-se num conjunto de anéis concêntricos aninhados que colapsam completamente e se voltam a esticar, impresso numa única peça sem necessidade de montagem.

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

Ao contrário dos outros endpoints do Creative Lab, este não tem um par de fases protótipo/build — não existem candidatos intermédios para escolher, pelo que uma única tarefa transporta a imagem até ao modelo 3D. Os controlos de geometria que a aplicação web expõe (tamanho, número de camadas, largura do intervalo, espessura de parede, profundidade de extrusão, protuberância) também não fazem parte do pedido: todas as tarefas são construídas com os mesmos valores predefinidos do lado do servidor.

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

Criar uma Tarefa de Fidget Retrátil

Gere um modelo de fidget retrátil a partir de uma fotografia de origem. Consulte O Objeto de Tarefa de Fidget Retrátil para a forma da resposta.

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

Parâmetros

Name
image_url
Type
string
Obrigatório
Description
Fotografia de origem para o Meshy transformar num fidget retrátil. Atualmente suportamos os formatos .jpg, .jpeg, .png e .webp.
Existem duas formas de fornecer a imagem:
- URL publicamente acessível: Um URL que está 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,<your base64-encoded image data>.
Um motivo com um contorno claro e fechado funciona melhor — a silhueta é o que se torna os anéis. Fundos com muitos elementos, vários motivos separados ou formas muito finas podem deixar 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 apresentação. Máximo de 100 caracteres. Esta é apenas uma etiqueta da tarefa; nada é gravado no modelo.

Retorna

A propriedade result da resposta contém o id da tarefa da tarefa de fidget retrátil recém-criada. Consulte periodicamente o endpoint Obter uma Tarefa ou subscreva o stream até a tarefa atingir SUCCEEDED, depois descarregue o STL para impressão a partir de model_urls.stl (e, quando presente, o GLB a partir de model_urls.glb para o pré-visualizar primeiro).

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_url fornecido não está num formato suportado (.jpg, .jpeg, .png, .webp).
- Dimensões da imagem fora do intervalo: A imagem é demasiado pequena, excede o tamanho máximo de ficheiro ou excede o número máximo de pixels.
- URL inacessível: Não foi possível descarregar o image_url (404 ou timeout).
- Data URI inválido: A cadeia base64 está malformada.
- Conteúdo assinalado: A imagem de entrada foi assinalada pela moderation de conteúdo impróprio (NSFW).
Name
401 - Unauthorized
Description
A autenticação falhou. Verifique a sua chave de API.
Name
402 - Payment Required
Description
Ou a sua conta está no plano gratuito — a criação de tarefas neste endpoint requer um plano pago — ou não tem créditos suficientes.
Name
403 - Forbidden
Description
A imagem de entrada foi assinalada por violação de propriedade intelectual.
Name
429 - Too Many Requests
Description
Excedeu o 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

Obter uma Tarefa de Fidget Colapsável

Obtenha uma tarefa de fidget colapsável a partir de um id de tarefa válido. Apenas as tarefas criadas através deste endpoint podem ser acedidas aqui — uma tarefa proveniente de outro endpoint da Creative Lab, ou criada na aplicação web, devolve 404.

Consulte O Objeto de Tarefa de Fidget Colapsável para conhecer a estrutura da resposta.

Parâmetros

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

Devolve

A resposta contém o objeto da 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

Eliminar 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. As tarefas que já estão IN_PROGRESS são canceladas sem reembolso (o worker pode já estar a consumir recursos). As 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 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á se encontra num estado terminal e não pode ser cancelada.
Name
404 - Not Found
Description
A tarefa não existe, pertence a outro utilizador 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 Colapsável

Transmite atualizações em tempo real para uma tarefa de fidget colapsável através de 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 fecha o stream.

Parâmetros

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

Retorna

Retorna um stream de objetos de tarefa Collapsible Fidget 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

Obtenha uma lista paginada das suas tarefas de fidget colapsável. Apenas são incluídas as tarefas criadas através deste endpoint.

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 itens por página. O máximo permitido é 100 itens.
Name
sort_by
Type
string
predefinição -created_at
Description
Campo pelo qual ordenar. Valores disponíveis:
- +created_at: Ordenar por hora de criação em ordem ascendente.
- -created_at: Ordenar por hora de criação em ordem descendente.

Retorna

Devolve 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 monitoriza para transformar uma foto de origem num modelo de fidget colapsável pronto a imprimir. É uma tarefa de estágio único: não existe protótipo a partir do qual encadear, e a silhueta intermédia não faz parte da resposta.

Propriedades

Name
id
Type
string
Description
Identificador único da tarefa. Embora utilizemos um UUID ordenável por k (k-sortable) para os ids das tarefas como detalhe de implementação, 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 quando esta foi criada. Cadeia vazia se não tiver sido fornecido nenhum nome.
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
Progress da tarefa. Se a tarefa ainda não tiver começado, esta propriedade será 0. Assim que a tarefa for bem-sucedida, passará a 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 a norma RFC 3339. Por exemplo, sexta-feira, 1 de setembro de 2023, 12:00:00 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 tiver sido iniciada, esta propriedade será null.
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á 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 estado 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 estado da tarefa é PENDING, IN_PROGRESS ou SUCCEEDED. Devolve 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).
Name
model_urls
Type
object
Description
URLs transferíveis para o modelo 3D gerado. Preenchido assim que a tarefa tiver SUCCEEDED: o stl está sempre presente, o glb apenas quando a renderização de pré-visualização for bem-sucedida.
- Name
  stl
  Type
  string
  Description
  URL transferível para o ficheiro STL. Este é o resultado imprimível — envie-o diretamente para um software de corte.
- Name
  glb
  Type
  string
  Description
  URL transferível para o ficheiro GLB, para pré-visualizar o modelo num visualizador 3D. As suas cores destinam-se apenas a pré-visualização: o STL não contém cor, e um fidget impresso obtém a 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 por completo de model_urls, por isso deve lê-la de forma defensiva — o stl é o resultado final e está sempre presente numa 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=***"
  }
}