API de Fidget Colapsável do Creative Lab

Transforme uma fotografia num brinquedo fidget colapsável imprimível de uma só vez numa única tarefa. A silhueta do sujeito transforma-se em anéis concêntricos aninhados que colapsam na horizontal e voltam a esticar-se. O brinquedo é impresso de uma só peça, sem montagem.

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

Ao contrário dos outros endpoints do Creative Lab, este não tem fases separadas de protótipo e de construção. Não existem imagens candidatas entre as quais escolher, pelo que uma única tarefa transforma a fotografia num modelo 3D.

O pedido também não tem definições de geometria. A aplicação web permite definir o tamanho, o número de camadas, a largura do espaço, a espessura de parede, a profundidade de extrusão e o abaulamento. Todas as tarefas da API utilizam os mesmos valores predefinidos para estes parâmetros.

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 fotografia. Para os campos da tarefa, consulte O objeto da tarefa Fidget Colapsável.

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

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"
}

Parâmetros

Name
image_url
Type
string
Obrigatório
Description
A fotografia a transformar num fidget colapsável, como um URL público ou um data URI (data:image/jpeg;base64,<your base64-encoded image data>).
A imagem deve ser um ficheiro JPG, JPEG, PNG ou WebP de, no máximo, 20 MB.
A silhueta do sujeito torna-se nos anéis, pelo que um sujeito com um contorno único e fechado funciona melhor. Um fundo com muitos elementos, vários sujeitos separados, ou formas muito finas podem deixar área insuficiente para as paredes aninhadas. Nesse caso, a tarefa falha.
Name
name
Type
string
Description
Um nome para a tarefa, com até 100 carateres. É devolvido no campo name da tarefa, e a Meshy não o grava no modelo. Um nome mais longo devolve 400.

Retorna

O campo result contém o ID da nova tarefa. Obtenha a tarefa ou transmita-a em streaming até que status seja SUCCEEDED. Depois, transfira o ficheiro STL imprimível a partir de model_urls.stl. Para pré-visualizar primeiro o modelo, transfira o ficheiro GLB a partir de model_urls.glb quando estiver presente.

Modos de falha

Name
400 - Bad Request
Description
O pedido não pode ser executado. Por exemplo:
- image_url está em falta.
- A imagem não é um ficheiro JPG, JPEG, PNG ou WebP.
- A imagem é demasiado pequena, excede os 20 MB, ou excede o número máximo de píxeis.
- A Meshy não consegue transferir a imagem, por exemplo porque o URL devolve 404 ou expira o tempo de espera.
- O data URI não é um base64 válido.
- A imagem foi assinalada como NSFW.
A mensagem de erro indica qual o problema encontrado. Corrija o pedido e envie-o novamente.
Name
401 - Unauthorized
Description
A chave de API está em falta ou é inválida. Verifique o cabeçalho Authorization.
Name
402 - Payment Required
Description
Aplica-se uma das seguintes situações:
- A conta não tem créditos suficientes.
- A chave de API, o espaço de trabalho ou o membro atingiu o limite de créditos.
- A conta está num plano gratuito.
Verifique os seus créditos e plano, e tente novamente.
Name
403 - Forbidden
Description
A sua equipa tem a Filtragem de IP ativada, e a Meshy assinalou a imagem por propriedade intelectual de terceiros. Envie uma imagem sobre a qual tem os direitos de utilização.
Name
429 - Too Many Requests
Description
Um dos seguintes limites foi atingido:
- Enviou mais pedidos do que o seu limite de taxa permite. Aguarde alguns segundos e tente novamente. Consulte Limites de taxa.
- Há demasiadas tarefas suas em fila de espera ou em execução. Aguarde que algumas terminem e tente novamente.
- Num plano ilimitado sem créditos restantes, atingiu o número de tarefas que podem ser executadas sem créditos. Aguarde que uma tarefa termine, ou adicione créditos.
Name
500 - Internal Server Error
Description
A Meshy encontrou um erro de servidor, por exemplo porque não conseguiu executar a verificação de propriedade intelectual na imagem. A Meshy não cria a tarefa, e reembolsa quaisquer créditos que tenha cobrado. Tente o pedido novamente.

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

Obter uma tarefa Collapsible Fidget

Devolve uma tarefa Collapsible Fidget. Apenas são devolvidas tarefas criadas com este endpoint. Uma tarefa de outro endpoint do Creative Lab, ou uma criada na aplicação web, devolve 404.

Para os campos, consulte O objeto da tarefa Collapsible Fidget.

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=***"
  }
}

Parâmetros

Name
id
Type
path
Description
O ID da tarefa da resposta de criação.

Devoluções

O objeto da tarefa Collapsible Fidget.

Modos de falha

Name
400 - Bad Request
Description
id não é um ID de tarefa válido. Envie o ID result da resposta de criação.
Name
403 - Forbidden
Description
A sua equipa tem a opção IP Filtering ativada, e a Meshy sinalizou a imagem da tarefa por propriedade intelectual de terceiros. As equipas no plano Enterprise não recebem este erro. Crie uma tarefa a partir de uma imagem cujos direitos de utilização possui.
Name
404 - Not Found
Description
Nenhuma tarefa Collapsible Fidget com este ID pertence à sua conta, ou a tarefa não foi criada com este endpoint. Verifique o ID.
Name
500 - Internal Server Error
Description
A Meshy não conseguiu executar a verificação de propriedade intelectual. Repita o pedido.

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

Eliminar uma tarefa Collapsible Fidget

Cancela uma tarefa Collapsible Fidget. Cancelar uma tarefa PENDING reembolsa os seus créditos. Uma tarefa IN_PROGRESS é cancelada sem reembolso, porque um worker já a iniciou. Uma tarefa com um estado final (SUCCEEDED, FAILED ou CANCELED) não pode ser cancelada.

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

Parâmetros do caminho

Name
id
Type
path
Description
O ID da tarefa a cancelar.

Devolve

204 No Content com um corpo vazio.

Modos de falha

Name
400 - Bad Request
Description
Aplica-se uma das seguintes situações:
- id não é um ID de tarefa válido. Envie o ID result da resposta de criação.
- A tarefa já tem um estado final (SUCCEEDED, FAILED ou CANCELED), pelo que não pode ser cancelada.
Name
404 - Not Found
Description
Nenhuma tarefa Collapsible Fidget com este ID pertence à sua conta, ou a tarefa não foi criada com este endpoint. Verifique o ID.

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

Transmitir em stream a tarefa de Collapsible Fidget

Transmite as atualizações de uma tarefa de Collapsible Fidget como Server-Sent Events (SSE). Se a tarefa não existir ou não tiver sido criada através deste endpoint, o stream envia um evento error com status_code: 404 e fecha.

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 following PENDING frame is shortened 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=***"
  }
}

Parâmetros

Name
id
Type
path
Description
O ID da tarefa proveniente da resposta de criação.

Devolve

Um stream de objetos de tarefa de Collapsible Fidget. Cada evento contém o objeto de tarefa completo, tal como devolvido por Obter uma tarefa de Collapsible Fidget. Enquanto a tarefa está PENDING ou IN_PROGRESS, os seus campos de output continuam vazios (null, [], ou {}), e finished_at é null.

Se a Filtragem por IP bloquear o resultado da tarefa, o stream envia um evento error em seu lugar, com o status_code que um pedido get devolveria.

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

Listar tarefas de Fidget Colapsável

Devolve as suas tarefas de Fidget Colapsável, uma página de cada vez. Apenas são incluídas as tarefas criadas com este endpoint.

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=***"
    }
  }
]

Parâmetros de consulta

Name
page_num
Type
integer
predefinição 1
Description
A página a devolver, de 1 a 255. 0 devolve a primeira página. Um valor fora do intervalo 0 a 255 devolve 400.
Name
page_size
Type
integer
predefinição 10
Description
Número de tarefas por página, até 100. Um valor de 101 a 255 devolve 100 tarefas, e 0 utiliza o valor predefinido. Um valor fora do intervalo 0 a 255 devolve 400.
Name
sort_by
Type
string
predefinição -created_at
Description
A ordem de ordenação.
Valores disponíveis:
- -created_at: mais recentes primeiro
- +created_at: mais antigas primeiro

Devolve

Um array de objetos de tarefa de Fidget Colapsável.

O objeto de tarefa Collapsible Fidget

Uma tarefa Collapsible Fidget transforma uma fotografia num modelo de fidget colapsável pronto a imprimir. É uma tarefa de estágio único, pelo que não existe uma tarefa de protótipo a partir da qual encadear. A resposta não inclui a silhueta que a Meshy cria ao longo do processo.

Propriedades

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=***"
  }
}

Name
id
Type
string
Description
O ID da tarefa. Não dependa do seu formato.
Name
type
Type
string
Description
O tipo de tarefa, sempre creative-lab-fidget-collapsible.
Name
name
Type
string
Description
O name que enviou ao criar a tarefa, ou "" se não tiver enviado nenhum.
Name
status
Type
string
Description
O estado da tarefa.
Valores disponíveis:
- PENDING: a aguardar na fila
- IN_PROGRESS: a gerar o resultado
- SUCCEEDED: final, com o resultado
- FAILED: final, com o motivo em task_error
- CANCELED: final, sem resultado
Name
progress
Type
integer
Description
Percentagem do trabalho concluído, de 0 a 100. É 0 até a tarefa começar e 100 quando é bem-sucedida.
Name
created_at
Type
timestamp
Description
Momento em que a tarefa foi criada, em milissegundos Unix.
Name
started_at
Type
timestamp
Description
Momento em que um worker iniciou a tarefa, em milissegundos Unix. null até isso acontecer.
Name
finished_at
Type
timestamp
Description
Momento em que a tarefa atingiu um estado final, em milissegundos Unix. null até isso acontecer.
Name
expires_at
Type
timestamp
Description
Momento em que o resultado da tarefa expira, em milissegundos Unix. É 3 dias após finished_at, ou 3 dias após created_at até a tarefa terminar. Para contas Enterprise, que mantêm os resultados da API indefinidamente, é cerca de 100 anos depois. Consulte Retenção de recursos.
Name
preceding_tasks
Type
integer
Description
A posição da tarefa na fila enquanto está PENDING. 1 significa que é a próxima a começar. 0 depois de a tarefa sair da fila, e sempre 0 em resultados de listagem.
Name
task_error
Type
object
Description
O motivo pelo qual a tarefa falhou. null a menos que status seja FAILED. Consulte Erros.
Name
consumed_credits
Type
integer
Description
Número de créditos cobrados pela tarefa, após qualquer reembolso. Um pedido que devolve um erro não é cobrado. Uma tarefa falhada é 0, porque a Meshy a reembolsa. Cancelar só reembolsa uma tarefa enquanto esta estiver PENDING. Se a Meshy não conseguir ler a cobrança, uma resposta de obtenção ou de stream omite o campo, e um pedido de listagem devolve 500. Nesse caso, repita o pedido.
Name
model_urls
Type
object
Description
URLs de transferência para o modelo 3D, vazio até a tarefa ser bem-sucedida. Uma tarefa bem-sucedida tem sempre stl, e só tem glb se a Meshy tiver processado a pré-visualização.
- Name
  stl
  Type
  string
  Description
  URL de transferência para o ficheiro STL, que é o ficheiro a imprimir. Pode abri-lo diretamente num software de corte.
- Name
  glb
  Type
  string
  Description
  URL de transferência para um ficheiro GLB para pré-visualizar o modelo num visualizador 3D. As suas cores servem apenas para a pré-visualização. O ficheiro STL não tem cor, pelo que o fidget impresso adquire a sua cor do filamento.
  Se a Meshy não conseguir processar a pré-visualização, model_urls não tem a chave glb, por isso verifique se a chave existe antes de a ler. Uma tarefa SUCCEEDED tem sempre stl.