Creative Lab — API do Fidget Colapsável

Transforme uma foto de origem num brinquedo fidget colapsável para imprimir de uma só peça: a silhueta do sujeito transforma-se num conjunto de anéis concêntricos aninhados que colapsam de forma plana e se voltam a esticar, impressos numa só 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 de prototype/build — não existem candidatos intermédios entre os quais 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 espaço, 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 Colapsável

Gere um modelo de fidget colapsável a partir de uma fotografia 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
Fotografia de origem para a Meshy transformar num fidget colapsável. Atualmente suportamos os formatos .jpg, .jpeg, .png e .webp.
Existem duas formas de fornecer a imagem:
- URL publicamente acessível: Um 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,<your base64-encoded image data>.
Um motivo com um contorno único e fechado funciona melhor — a silhueta é o que se torna nos anéis. Fundos com muitos elementos, vários motivos separados ou formas muito finas podem deixar pouca área para as paredes encaixadas, 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. Isto é apenas uma etiqueta de 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. Consulte periodicamente o endpoint Obter uma Tarefa ou subscreva o stream até a tarefa atingir SUCCEEDED, depois descarregue o STL imprimível 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 tem um 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 píxeis.
- URL inacessível: Não foi possível transferir 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 explícito (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 aqui endereçadas — uma tarefa de outro endpoint da Creative Lab, ou uma criada na aplicação web, devolve 404.

Consulte O Objeto da Tarefa de Fidget Colapsável para 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

Cancele 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á se encontram 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.

Retorna

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 um utilizador 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 Tarefa de Fidget Colapsável em Streaming

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 payload event: error 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. Cada frame transporta o objeto de tarefa completo para a etapa — a mesma forma que o endpoint Get retorna — pelo que, 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

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 tamanho da 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

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 de Tarefa Fidget Colapsável

O objeto de Tarefa Fidget Colapsável é uma unidade de trabalho que a Meshy controla para transformar uma foto de origem num modelo de fidget colapsável imprimível diretamente. É uma tarefa de estágio único: não há 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 k-sortable para os ids de tarefa 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 na criação da tarefa. Cadeia vazia se não tiver sido fornecido nenhum nome.
Name
status
Type
string
Description
Estado da tarefa. Os valores possíveis são PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
O progress da tarefa. Se a tarefa ainda não tiver começado, esta propriedade será 0. Assim que a tarefa tiver sido concluída com sucesso, passará a 100.
Name
created_at
Type
timestamp
Description
Carimbo de data/hora da criação da tarefa, 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 do início da tarefa, em milissegundos. Se a tarefa ainda não tiver começado, esta propriedade será null.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora da conclusão da tarefa, em milissegundos. Se a tarefa ainda não tiver terminado, esta propriedade será null.
Name
expires_at
Type
timestamp
Description
Carimbo de data/hora de expiração do resultado da tarefa, 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 de erro para tarefas falhadas. 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: stl está sempre presente, 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 entregável 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 com base no melhor esforço: quando a renderização de pré-visualização não está disponível, a chave é totalmente omitida de model_urls, pelo que deve ler o valor de forma defensiva — stl é o entregável 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=***"
  }
}