Creative Lab — API de Fidget Colapsável

Transforme uma foto de origem em um brinquedo fidget colapsável pronto para impressão: a silhueta do sujeito se torna um conjunto de anéis concêntricos aninhados que 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 tarefa carrega a imagem até chegar a um modelo 3D. Os controles de geometria que o aplicativo web expõe (tamanho, número de camadas, largura do vão, espessura de parede, profundidade de extrusão, abaulamento) também não fazem parte da requisição: toda tarefa é construída com os padrões definidos no 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 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 formas 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 fechado funciona melhor — a silhueta é o que se torna os anéis. Fundos com muitos 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 opcional da tarefa para fins de exibição. Máximo de 100 caracteres. Este é apenas um rótulo da 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. Faça polling no endpoint Obter uma Tarefa ou inscreva-se no stream até que a tarefa alcance 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 requisição foi 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 em base64 está malformada.
    • Conteúdo sinalizado: A imagem de entrada foi sinalizada pela moderation de NSFW.
  • Name
    401 - Unauthorized
    Description

    A autenticação falhou. 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.cn/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 Retrátil

Recupera uma tarefa de fidget retrátil a partir de um id de tarefa válido. Apenas tarefas criadas através deste endpoint podem ser acessadas aqui — uma tarefa de outro endpoint do Creative Lab, ou uma criada no aplicativo web, retorna 404.

Consulte O Objeto de Tarefa de Fidget Retrátil para o formato da resposta.

Parâmetros

  • Name
    id
    Type
    path
    Description

    Identificador único da tarefa de fidget retrátil a ser recuperada.

Retornos

A resposta contém o objeto de tarefa de fidget retrátil.

Request

GET
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.cn/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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/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 através deste endpoint.

Request

DELETE
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.cn/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 Retrátil

Transmita atualizações em tempo real para uma tarefa de fidget retrátil via 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 encerra o stream.

Parâmetros

  • Name
    id
    Type
    path
    Description

    Identificador único da tarefa de fidget retrátil a ser transmitida.

Retornos

Retorna um stream de objetos de tarefa Fidget Retrátil 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.cn/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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}
GET/openapi/creative-lab/fidget-collapsible/v1

Listar Tarefas de Fidget Colapsável

Recupera uma lista paginada das suas tarefas de fidget colapsável. Somente as tarefas criadas por meio 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 a ser usado para ordenação. Valores disponíveis:

    • +created_at: Ordenar pelo horário de criação em ordem crescente.
    • -created_at: Ordenar pelo horário de criação em ordem decrescente.

Retornos

Retorna uma lista paginada de o objeto de tarefa de fidget colapsável.

Request

GET
/openapi/creative-lab/fidget-collapsible/v1
curl https://api.meshy.cn/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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.cn/***/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 imprimível diretamente na impressora (print-in-place). É uma tarefa de estágio único: não há protótipo a partir 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 os ids de tarefas como detalhe de implementação, você não deve fazer nenhuma suposição 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 no momento da criação. String vazia caso nenhum nome tenha sido 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, esta propriedade será 0. Assim que a tarefa for concluída com sucesso, ela 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, esta 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, 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 status 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 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 assume a cor do filamento. O GLB é fornecido em regime de melhor esforço: quando a renderização de pré-visualização não está disponível, a chave é omitida completamente 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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}