API de Fidget Colapsável do Creative Lab

Transforme uma foto em um brinquedo fidget colapsável para impressão direta em uma única tarefa. A silhueta do sujeito se torna anéis concêntricos aninhados que se recolhem achatados e se esticam novamente. O brinquedo é impresso em uma única peça, sem montagem.

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

Diferente dos outros endpoints do Creative Lab, este não possui etapas separadas de protótipo e construção. Não há imagens candidatas para escolher, então uma única tarefa transforma a foto em um modelo 3D.

A requisição também não possui configurações de geometria. O aplicativo web permite definir o tamanho, a quantidade de camadas, a largura do vão, a espessura de parede, a profundidade de extrusão e o abaulamento. Toda tarefa da API usa os mesmos valores padrão para esses 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 foto. Para os campos da tarefa, veja O objeto de tarefa de 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 foto a ser transformada em um fidget colapsável, como uma URL pública ou um data URI (data:image/jpeg;base64,<seus dados de imagem codificados em base64>).
A imagem deve ser um arquivo JPG, JPEG, PNG ou WebP de no máximo 20 MB.
A silhueta do assunto se torna os anéis, então um assunto com um contorno único e fechado funciona melhor. Um fundo muito carregado, vários assuntos 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 caracteres. Ele retorna no campo name da tarefa, e o Meshy não o grava no modelo. Um nome mais longo retorna 400.

Retornos

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

Modos de falha

Name
400 - Bad Request
Description
A solicitação não pode ser executada. Por exemplo:
- image_url está ausente.
- A imagem não é um arquivo JPG, JPEG, PNG ou WebP.
- A imagem é muito pequena, ultrapassa 20 MB ou excede a contagem máxima de pixels.
- O Meshy não consegue baixar a imagem, por exemplo porque a URL retorna 404 ou expira o tempo limite.
- O data URI não é um base64 válido.
- A imagem foi sinalizada como NSFW.
A mensagem de erro indica qual problema foi encontrado. Corrija a solicitação e envie-a novamente.
Name
401 - Unauthorized
Description
A chave de API está ausente ou é inválida. Verifique o cabeçalho Authorization.
Name
402 - Payment Required
Description
Um destes se aplica:
- A conta não tem créditos suficientes.
- A chave de API, o espaço de trabalho ou o membro atingiu seu limite de créditos.
- A conta está no plano gratuito.
Verifique seus créditos e plano, depois tente novamente.
Name
403 - Forbidden
Description
Sua equipe tem a opção IP Filtering ativada, e o Meshy sinalizou a imagem por propriedade intelectual de terceiros. Envie uma imagem que você tem o direito de usar.
Name
429 - Too Many Requests
Description
Um destes limites foi atingido:
- Você enviou mais solicitações do que o seu limite de taxa permite. Aguarde alguns segundos e tente novamente. Veja Limites de taxa.
- Muitas das suas tarefas estão na fila ou em execução. Aguarde algumas terminarem e tente novamente.
- Em um plano ilimitado sem créditos restantes, você atingiu o número de tarefas que podem ser executadas sem créditos. Aguarde uma tarefa terminar ou adicione créditos.
Name
500 - Internal Server Error
Description
O Meshy encontrou um erro de servidor, por exemplo porque não conseguiu executar a verificação de propriedade intelectual na imagem. O Meshy não cria a tarefa e reembolsa quaisquer créditos cobrados. Tente a solicitação novamente.

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

Get a Collapsible Fidget task

Retorna uma tarefa de Collapsible Fidget. Somente tarefas criadas com este endpoint são retornadas. Uma tarefa de outro endpoint do Creative Lab, ou uma criada no aplicativo web, retorna 404.

Para os campos, consulte O objeto de 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 retornado na resposta de criação.

Retornos

O objeto de 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
Sua equipe está com a Filtragem de IP ativada, e a Meshy sinalizou a imagem da tarefa por propriedade intelectual de terceiros. Equipes no plano Enterprise não recebem este erro. Crie uma tarefa a partir de uma imagem que você tenha o direito de usar.
Name
404 - Not Found
Description
Nenhuma tarefa de 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. Tente novamente a solicitação.

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

Excluir uma tarefa de Collapsible Fidget

Cancela uma tarefa de Collapsible Fidget. Cancelar uma tarefa PENDING reembolsa seus créditos. Uma tarefa IN_PROGRESS é cancelada sem reembolso, porque um worker já a iniciou. Uma tarefa com status 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 de caminho

Name
id
Type
path
Description
O ID da tarefa a ser cancelada.

Retornos

204 No Content com corpo vazio.

Modos de falha

Name
400 - Bad Request
Description
Uma destas situações se aplica:
- id não é um ID de tarefa válido. Envie o ID result da resposta de criação.
- A tarefa já tem um status final (SUCCEEDED, FAILED ou CANCELED), então não pode ser cancelada.
Name
404 - Not Found
Description
Nenhuma tarefa de 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

Fazer streaming de uma tarefa de Fidget Colapsável

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

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 retornado na resposta de criação.

Retornos

Um stream de objetos de tarefa de Fidget Colapsável. Cada evento contém o objeto de tarefa completo, da mesma forma que Obter uma tarefa de Fidget Colapsável o retorna. Enquanto a tarefa estiver PENDING ou IN_PROGRESS, seus campos de saída permanecem vazios (null, [] ou {}), e finished_at é null.

Se a Filtragem de IP bloquear o resultado da tarefa, o stream envia um evento error em seu lugar, com o status_code que uma requisição get retornaria.

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

Listar tarefas de Collapsible Fidget

Retorna suas tarefas de Collapsible Fidget, uma página por vez. Somente as tarefas criadas com este endpoint são incluídas.

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
padrão 1
Description
A página a ser retornada, de 1 a 255. 0 retorna a primeira página. Um valor fora do intervalo de 0 a 255 retorna 400.
Name
page_size
Type
integer
padrão 10
Description
Número de tarefas por página, até 100. Um valor entre 101 e 255 retorna 100 tarefas, e 0 usa o valor padrão. Um valor fora do intervalo de 0 a 255 retorna 400.
Name
sort_by
Type
string
padrão -created_at
Description
A ordem de classificação.
Valores disponíveis:
- -created_at: mais recentes primeiro
- +created_at: mais antigas primeiro

Retornos

Um array de objetos de tarefa Collapsible Fidget.

O objeto de tarefa Collapsible Fidget

Uma tarefa Collapsible Fidget transforma uma foto em um modelo de fidget colapsável para impressão direta (print-in-place). É uma tarefa de estágio único, então não há uma tarefa de protótipo da qual encadear. A resposta não inclui a silhueta que o 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 da tarefa, sempre creative-lab-fidget-collapsible.
Name
name
Type
string
Description
O name que você enviou ao criar a tarefa, ou "" se você não enviou um.
Name
status
Type
string
Description
O status da tarefa.
Valores disponíveis:
- PENDING: aguardando na fila
- IN_PROGRESS: gerando o resultado
- SUCCEEDED: final, com o resultado
- FAILED: final, com o motivo em task_error
- CANCELED: final, sem resultado
Name
progress
Type
integer
Description
Porcentagem do trabalho concluído, de 0 a 100. É 0 até a tarefa começar e 100 quando ela é bem-sucedida.
Name
created_at
Type
timestamp
Description
Horário em que a tarefa foi criada, em milissegundos Unix.
Name
started_at
Type
timestamp
Description
Horário em que um worker iniciou a tarefa, em milissegundos Unix. null até então.
Name
finished_at
Type
timestamp
Description
Horário em que a tarefa atingiu um status final, em milissegundos Unix. null até então.
Name
expires_at
Type
timestamp
Description
Horário 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. Veja Retenção de recursos.
Name
preceding_tasks
Type
integer
Description
A posição da tarefa na fila enquanto ela está PENDING. 1 significa que ela começa em seguida. 0 depois que a tarefa sai da fila, e sempre 0 em resultados de listagem.
Name
task_error
Type
object
Description
Por que a tarefa falhou. null a menos que status seja FAILED. Veja Erros.
Name
consumed_credits
Type
integer
Description
Número de créditos cobrados pela tarefa, após qualquer reembolso. Uma requisição que retorna um erro não é cobrada. Uma tarefa que falhou é 0, porque o Meshy a reembolsa. Cancelar reembolsa uma tarefa apenas enquanto ela está PENDING. Se o Meshy não conseguir ler a cobrança, uma resposta de get ou stream deixa o campo de fora, e uma requisição de listagem retorna 500. Nesse caso, tente a requisição novamente.
Name
model_urls
Type
object
Description
URLs de download para o modelo 3D, vazio até a tarefa ser bem-sucedida. Uma tarefa bem-sucedida sempre tem stl, e tem glb apenas se o Meshy renderizou a prévia.
- Name
  stl
  Type
  string
  Description
  URL de download para o arquivo STL, que é o arquivo a ser impresso. Você pode abri-lo diretamente em um fatiador.
- Name
  glb
  Type
  string
  Description
  URL de download para um arquivo GLB para pré-visualizar o modelo em um visualizador 3D. Suas cores são apenas para a prévia. O arquivo STL não tem cor, então o fidget impresso recebe sua cor do filamento.
  Se o Meshy não conseguir renderizar a prévia, model_urls não tem a chave glb, então verifique a chave antes de lê-la. Uma tarefa SUCCEEDED sempre tem stl.