Creative Lab — Skládací fidget API

Proměňte zdrojovou fotografii na tisknutelnou skládací fidget hračku: silueta objektu se promění v sadu vnořených soustředných kruhů, které se dají složit naplocho a znovu roztáhnout, vytištěnou v jednom kuse bez nutnosti montáže.

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

Na rozdíl od ostatních endpointů Creative Lab tento nemá dvojici fází prototyp/sestavení — neexistují žádní mezikandidáti, mezi kterými by bylo možné vybírat, takže jedna úloha provede obrázek celou cestou až k 3D modelu. Ani ovládací prvky geometrie, které webová aplikace zobrazuje (velikost, počet vrstev, šířka mezery, tloušťka stěny, hloubka extruze, vydutí), nejsou součástí požadavku: každá úloha se sestavuje se stejnými výchozími hodnotami na straně serveru.

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

Vytvoření úlohy Collapsible Fidget

Vygenerujte model skládacího fidgetu (collapsible fidget) ze zdrojové fotografie. Podrobnosti o tvaru odpovědi naleznete v části Objekt úlohy Collapsible Fidget.

Každá úloha stojí 6 kreditů a vyžaduje placený plán.

Parametry

  • Name
    image_url
    Type
    string
    Povinné
    Description

    Zdrojová fotografie, kterou Meshy přemění na skládací fidget. V současnosti podporujeme formáty .jpg, .jpeg, .png a .webp.

    Obrázek lze poskytnout dvěma způsoby:

    • Veřejně dostupná URL adresa: URL adresa přístupná z veřejného internetu.
    • Data URI: Base64 kódované data URI obrázku. Příklad data URI: data:image/jpeg;base64,<vaše base64 kódovaná data obrázku>.

    Nejlépe funguje objekt s jedním jasným, uzavřeným obrysem — právě siluetа se stává prstenci. Rušná pozadí, více samostatných objektů nebo velmi tenké tvary mohou ponechat příliš málo místa pro vnořené stěny, a úloha pak selže s chybou úlohy.

  • Name
    name
    Type
    string
    Description

    Volitelný název úlohy pro zobrazení. Maximálně 100 znaků. Jedná se pouze o štítek úlohy; na modelu se nic nevyrytí.

Návratové hodnoty

Vlastnost result odpovědi obsahuje id úlohy nově vytvořené úlohy Collapsible Fidget. Dotazujte se na koncový bod Získání úlohy nebo se přihlaste k odběru streamu, dokud úloha nedosáhne stavu SUCCEEDED, a poté stáhněte tisknutelný STL soubor z model_urls.stl (a pokud je k dispozici, GLB soubor z model_urls.glb pro jeho náhled).

Režimy selhání

  • Name
    400 - Bad Request
    Description

    Požadavek byl nepřijatelný. Běžné příčiny:

    • Chybějící parametr: image_url je povinný.
    • Neplatný formát obrázku: Poskytnutý image_url není v podporovaném formátu (.jpg, .jpeg, .png, .webp).
    • Rozměry obrázku mimo rozsah: Obrázek je příliš malý, přesahuje maximální velikost souboru nebo přesahuje maximální počet pixelů.
    • Nedostupná URL adresa: image_url se nepodařilo stáhnout (404 nebo timeout).
    • Neplatné Data URI: Base64 řetězec má nesprávný formát.
    • Obsah byl označen: Vstupní obrázek byl označen moderací NSFW obsahu.
  • Name
    401 - Unauthorized
    Description

    Autentizace selhala. Zkontrolujte prosím svůj API klíč.

  • Name
    402 - Payment Required
    Description

    Buď je váš účet na bezplatném plánu — vytvoření úlohy u tohoto koncového bodu vyžaduje placený plán — nebo nemáte dostatek kreditů.

  • Name
    403 - Forbidden
    Description

    Vstupní obrázek byl označen za porušení práv duševního vlastnictví.

  • Name
    429 - Too Many Requests
    Description

    Překročili jste limit rychlosti.

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

Získání úlohy Collapsible Fidget

Získá úlohu collapsible fidget na základě platného id úlohy. Zde lze adresovat pouze úlohy vytvořené prostřednictvím tohoto koncového bodu — úloha z jiného koncového bodu Creative Lab, nebo úloha vytvořená ve webové aplikaci, vrátí 404.

Tvar odpovědi naleznete v části Objekt úlohy Collapsible Fidget.

Parametry

  • Name
    id
    Type
    path
    Description

    Jedinečný identifikátor úlohy collapsible fidget, kterou chcete získat.

Návratová hodnota

Odpověď obsahuje objekt úlohy 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=***"
  }
}
DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Smazání úlohy skládacího fidgetu

Zruší úlohu skládacího fidgetu. Pokud je úloha stále ve stavu PENDING, kredity spotřebované při vytvoření jsou vráceny. Úlohy, které jsou již IN_PROGRESS, jsou zrušeny bez vrácení kreditů (worker může již čerpat zdroje). Úlohy, které již dosáhly koncového stavu (SUCCEEDED, FAILED, CANCELED), nelze zrušit.

Parametry cesty

  • Name
    id
    Type
    path
    Description

    Jedinečný identifikátor úlohy skládacího fidgetu, kterou chcete zrušit.

Návratová hodnota

Při úspěchu vrací 204 No Content s prázdným tělem.

Chybové stavy

  • Name
    400 - Bad Request
    Description

    Úloha se již nachází v koncovém stavu a nelze ji zrušit.

  • Name
    404 - Not Found
    Description

    Úloha neexistuje, patří jinému uživateli nebo nebyla vytvořena prostřednictvím tohoto koncového bodu.

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

Streamování úlohy skládacího fidgetu

Streamujte aktualizace v reálném čase pro úlohu skládacího fidgetu prostřednictvím Server-Sent Events (SSE). Úloha, která neexistuje nebo nebyla vytvořena prostřednictvím tohoto koncového bodu, vyšle jediný event: error payload se status_code: 404 a stream se uzavře.

Parametry

  • Name
    id
    Type
    path
    Description

    Jedinečný identifikátor úlohy skládacího fidgetu, kterou chcete streamovat.

Návratová hodnota

Vrací stream objektů úlohy Collapsible Fidget ve formě Server-Sent Events. Každý snímek nese celý objekt úlohy pro danou fázi — stejnou strukturu, jakou vrací endpoint Get — takže dokud je úloha ve stavu PENDING nebo IN_PROGRESS, výstupní pole prostě ještě nejsou naplněna (null, [] nebo {}) a finished_at má hodnotu 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

Získat seznam úloh Collapsible Fidget

Načte stránkovaný seznam vašich úloh collapsible fidget. Zahrnuty jsou pouze úlohy vytvořené prostřednictvím tohoto koncového bodu.

Parametry dotazu

  • Name
    page_num
    Type
    integer
    výchozí 1
    Description

    Číslo stránky pro stránkování.

  • Name
    page_size
    Type
    integer
    výchozí 10
    Description

    Limit velikosti stránky. Maximální povolená hodnota je 100 položek.

  • Name
    sort_by
    Type
    string
    výchozí -created_at
    Description

    Pole, podle kterého se má řadit. Dostupné hodnoty:

    • +created_at: Seřadit podle času vytvoření vzestupně.
    • -created_at: Seřadit podle času vytvoření sestupně.

Návratová hodnota

Vrací stránkovaný seznam objektů úlohy collapsible fidget.

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

Objekt úlohy Collapsible Fidget Task

Objekt Collapsible Fidget Task je pracovní jednotka, kterou Meshy sleduje za účelem přeměny zdrojové fotografie na skládatelný fidget model tisknutelný na místě (print-in-place). Jde o jednostupňovou úlohu: neexistuje žádný prototyp, ze kterého by se navazovalo, a mezistupňová silueta není součástí odpovědi.

Vlastnosti

  • Name
    id
    Type
    string
    Description

    Jedinečný identifikátor úlohy. Ačkoli jako implementační detail používáme pro id úloh k-sortable UUID, neměli byste dělat žádné předpoklady o formátu id.

  • Name
    type
    Type
    string
    Description

    Typ úlohy. Hodnota je creative-lab-fidget-collapsible.

  • Name
    name
    Type
    string
    Description

    Název úlohy zadaný při jejím vytvoření. Prázdný řetězec, pokud nebyl název zadán.

  • Name
    status
    Type
    string
    Description

    Stav úlohy. Možné hodnoty jsou PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Průběh (progress) úlohy. Pokud úloha ještě nebyla zahájena, bude tato hodnota 0. Jakmile úloha úspěšně skončí, hodnota se změní na 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Časové razítko vytvoření úlohy, v milisekundách.

    Časové razítko představuje počet milisekund, které uplynuly od 1. ledna 1970 UTC, v souladu se standardem RFC 3339. Například pátek 1. září 2023 12:00:00 GMT je vyjádřen jako 1693569600000. Toto platí pro všechna časová razítka v Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Časové razítko zahájení úlohy, v milisekundách. Pokud úloha ještě nebyla zahájena, bude tato hodnota null.

  • Name
    finished_at
    Type
    timestamp
    Description

    Časové razítko dokončení úlohy, v milisekundách. Pokud úloha ještě není dokončena, bude tato hodnota null.

  • Name
    expires_at
    Type
    timestamp
    Description

    Časové razítko vypršení platnosti výsledku úlohy, v milisekundách.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Počet předcházejících úloh.

    Hodnota tohoto pole má smysl pouze tehdy, když je stav úlohy PENDING.

  • Name
    task_error
    Type
    object
    Description

    Podrobnosti o chybě u neúspěšných úloh. Úplný popis objektu task_error najdete v Chyby.

  • Name
    consumed_credits
    Type
    integer
    Description

    Počet kreditů spotřebovaných touto úlohou. Je přítomen, pokud je stav úlohy PENDING, IN_PROGRESS nebo SUCCEEDED. U úloh se stavem FAILED vrací 0 (kredity jsou při neúspěchu vráceny).

  • Name
    model_urls
    Type
    object
    Description

    URL adresy pro stažení vygenerovaného 3D modelu. Jsou vyplněny, jakmile úloha dosáhne stavu SUCCEEDED: stl je vždy přítomen, glb pouze tehdy, když se náhledové vykreslení podařilo.

    • Name
      stl
      Type
      string
      Description

      URL adresa pro stažení souboru STL. Toto je tisknutelný výstup — pošlete jej přímo do slicer.

    • Name
      glb
      Type
      string
      Description

      URL adresa pro stažení souboru GLB, pro náhled modelu ve 3D prohlížeči. Jeho barvy slouží pouze k náhledu: STL nenese žádnou barvu a vytištěný fidget získává barvu podle filamentu. GLB je poskytován na bázi nejlepší snahy (best-effort): pokud náhledové vykreslení není k dispozici, klíč je z model_urls zcela vynechán, takže jej čtěte obranně — stl je konečný výstup a u úlohy se stavem SUCCEEDED je vždy přítomen.

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