Creative Lab Collapsible Fidget API

Proměňte fotografii na skládací fidget hračku tisknutelnou na jeden kus v rámci jednoho úkolu. Silueta objektu se promění v soustředné kruhy, které se dají stlačit naplocho a opět roztáhnout. Hračka se tiskne vcelku, bez nutnosti montáže.

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

Na rozdíl od ostatních endpointů Creative Lab tento nemá samostatné fáze prototypu a sestavení. Neexistují žádné kandidátní obrázky, ze kterých by bylo možné vybírat, takže jediný úkol promění fotografii přímo na 3D model.

Požadavek rovněž neobsahuje žádná nastavení geometrie. Webová aplikace umožňuje nastavit velikost, počet vrstev, šířku mezery, tloušťku stěny, hloubku extruze a vyboulení. Každý úkol API pro ně používá stejné výchozí hodnoty.

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

Vytvoření úkolu Collapsible Fidget

Vygeneruje skládací fidget model z fotografie. Pole úkolu najdete v části Objekt úkolu Collapsible Fidget.

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

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

Parametry

Name
image_url
Type
string
Povinné
Description
Fotografie, která se má přeměnit na skládací fidget, zadaná jako veřejná URL adresa nebo jako data URI (data:image/jpeg;base64,<vaše data obrázku zakódovaná v base64>).
Obrázek musí být soubor JPG, JPEG, PNG nebo WebP o velikosti maximálně 20 MB.
Silueta objektu se stává prstenci, takže nejlépe funguje objekt s jedním jasným, uzavřeným obrysem. Rušné pozadí, více samostatných objektů nebo velmi tenké tvary mohou ponechat příliš málo prostoru pro vnořené stěny. V takovém případě úkol selže.
Name
name
Type
string
Description
Název úkolu, maximálně 100 znaků. Vrátí se v poli name úkolu a Meshy jej na model nevyrývá. Delší název vrátí 400.

Návratové hodnoty

Pole result obsahuje ID nového úkolu. Získejte úkol nebo jej streamujte, dokud status nebude SUCCEEDED. Poté stáhněte tisknutelný soubor STL z model_urls.stl. Chcete-li model nejprve zobrazit v náhledu, stáhněte soubor GLB z model_urls.glb, pokud je k dispozici.

Režimy selhání

Name
400 - Bad Request
Description
Požadavek nelze spustit. Například:
- image_url chybí.
- Obrázek není soubor JPG, JPEG, PNG ani WebP.
- Obrázek je příliš malý, přesahuje 20 MB nebo přesahuje maximální počet pixelů.
- Meshy nemůže obrázek stáhnout, například proto, že URL adresa vrací 404 nebo vyprší časový limit.
- Data URI nejsou platné v kódování base64.
- Obrázek byl označen jako NSFW.
Chybová zpráva uvádí, jaký problém byl zjištěn. Opravte požadavek a odešlete jej znovu.
Name
401 - Unauthorized
Description
API klíč chybí nebo je neplatný. Zkontrolujte hlavičku Authorization.
Name
402 - Payment Required
Description
Platí jedna z těchto možností:
- Účet nemá dostatek kreditů.
- API klíč, pracovní prostor nebo člen dosáhl svého limitu kreditů.
- Účet je na bezplatném plánu.
Zkontrolujte své kredity a plán a zkuste to znovu.
Name
403 - Forbidden
Description
Váš tým má zapnuté Filtrování IP a Meshy obrázek označil kvůli duševnímu vlastnictví třetí strany. Odešlete obrázek, ke kterému máte práva k užití.
Name
429 - Too Many Requests
Description
Byl dosažen jeden z těchto limitů:
- Odeslali jste více požadavků, než povoluje váš limit rychlosti. Počkejte několik sekund a zkuste to znovu. Viz Limity rychlosti.
- Příliš mnoho vašich úkolů je ve frontě nebo se zpracovává. Počkejte, až se některé dokončí, a zkuste to znovu.
- V neomezeném plánu bez zbývajících kreditů jste dosáhli počtu úkolů, které mohou běžet bez kreditů. Počkejte, až se nějaký úkol dokončí, nebo přidejte kredity.
Name
500 - Internal Server Error
Description
V Meshy došlo k chybě serveru, například proto, že se nepodařilo provést kontrolu duševního vlastnictví u obrázku. Meshy úkol nevytvoří a vrátí veškeré kredity, které naúčtoval. Zkuste požadavek odeslat znovu.

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

Získání úlohy Collapsible Fidget

Vrátí úlohu Collapsible Fidget. Vráceny jsou pouze úlohy vytvořené pomocí tohoto koncového bodu. Úloha z jiného koncového bodu Creative Lab nebo úloha vytvořená ve webové aplikaci vrátí 404.

Popis polí najdete v části 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=***"
  }
}

Parametry

Name
id
Type
path
Description
ID úlohy z odpovědi na vytvoření.

Návratová hodnota

Objekt úlohy Collapsible Fidget.

Možné chyby

Name
400 - Bad Request
Description
id není platné ID úlohy. Odešlete ID result z odpovědi na vytvoření.
Name
403 - Forbidden
Description
Váš tým má zapnuté filtrování IP a Meshy u obrázku úlohy označilo duševní vlastnictví třetí strany. Týmy s plánem Enterprise tuto chybu nezískají. Vytvořte úlohu z obrázku, ke kterému máte práva na použití.
Name
404 - Not Found
Description
Žádná úloha Collapsible Fidget s tímto ID nepatří k vašemu účtu, nebo úloha nebyla vytvořena pomocí tohoto koncového bodu. Zkontrolujte ID.
Name
500 - Internal Server Error
Description
Meshy nemohlo spustit kontrolu duševního vlastnictví. Zopakujte požadavek.

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

Smazání úlohy Collapsible Fidget

Zruší úlohu Collapsible Fidget. Zrušení úlohy ve stavu PENDING vrátí její kredity. Úloha ve stavu IN_PROGRESS je zrušena bez vrácení kreditů, protože worker ji již začal zpracovávat. Úlohu s konečným stavem (SUCCEEDED, FAILED nebo CANCELED) nelze zrušit.

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

Parametry cesty

Name
id
Type
path
Description
ID úlohy, kterou chcete zrušit.

Návratová hodnota

204 No Content s prázdným tělem.

Chybové stavy

Name
400 - Bad Request
Description
Platí jedno z následujícího:
- id není platné ID úlohy. Odešlete ID result z odpovědi na vytvoření.
- Úloha již má konečný stav (SUCCEEDED, FAILED nebo CANCELED), takže ji nelze zrušit.
Name
404 - Not Found
Description
Úloha Collapsible Fidget s tímto ID nepatří k vašemu účtu, nebo nebyla vytvořena pomocí tohoto koncového bodu. Zkontrolujte ID.

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

Streamování úlohy Collapsible Fidget

Streamuje aktualizace úlohy Collapsible Fidget jako Server-Sent Events (SSE). Pokud úloha neexistuje nebo nebyla vytvořena přes tento koncový bod, stream odešle jednu událost error se status_code: 404 a následně se uzavře.

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

Parametry

Name
id
Type
path
Description
ID úlohy z odpovědi na vytvoření.

Návratová hodnota

Proud objektů úlohy Collapsible Fidget. Každá událost obsahuje celý objekt úlohy, přesně tak, jak jej vrací Získání úlohy Collapsible Fidget. Dokud je úloha ve stavu PENDING nebo IN_PROGRESS, jsou její výstupní pole stále prázdná (null, [] nebo {}) a finished_at je null.

Pokud IP Filtering zablokuje výsledek úlohy, stream místo něj odešle jednu událost error se status_code, který by vrátil požadavek typu get.

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

Seznam úloh Collapsible Fidget

Vrací vaše úlohy Collapsible Fidget, vždy po jedné stránce. Zahrnuty jsou pouze úlohy vytvořené pomocí tohoto koncového bodu.

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

Parametry dotazu

Name
page_num
Type
integer
výchozí 1
Description
Stránka, která se má vrátit, od 1 do 255. 0 vrátí první stránku. Hodnota mimo rozsah 0 až 255 vrátí 400.
Name
page_size
Type
integer
výchozí 10
Description
Počet úloh na stránku, až 100. Hodnota od 101 do 255 vrátí 100 úloh a 0 použije výchozí hodnotu. Hodnota mimo rozsah 0 až 255 vrátí 400.
Name
sort_by
Type
string
výchozí -created_at
Description
Pořadí řazení.
Dostupné hodnoty:
- -created_at: nejnovější první
- +created_at: nejstarší první

Návratová hodnota

Pole objektů úlohy Collapsible Fidget.

Objekt úkolu Collapsible Fidget

Úkol Collapsible Fidget promění fotografii v tisknutelný skládací fidget model (print-in-place). Jedná se o jednostupňový úkol, takže zde není žádný prototypový úkol, na který by navazoval. Odpověď neobsahuje siluetu, kterou Meshy vytváří po cestě.

Vlastnosti

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
ID úkolu. Nespoléhejte na jeho formát.
Name
type
Type
string
Description
Typ úkolu, vždy creative-lab-fidget-collapsible.
Name
name
Type
string
Description
name, který jste odeslali při vytváření úkolu, nebo "", pokud jste žádný neodeslali.
Name
status
Type
string
Description
Stav úkolu.
Dostupné hodnoty:
- PENDING: čeká ve frontě
- IN_PROGRESS: generuje se výsledek
- SUCCEEDED: konečný stav, s výsledkem
- FAILED: konečný stav, s důvodem v task_error
- CANCELED: konečný stav, bez výsledku
Name
progress
Type
integer
Description
Procento dokončené práce, od 0 do 100. Je 0, dokud úkol nezačne, a 100, když je úspěšně dokončen.
Name
created_at
Type
timestamp
Description
Čas vytvoření úkolu, v milisekundách Unixového času.
Name
started_at
Type
timestamp
Description
Čas, kdy worker úkol zahájil, v milisekundách Unixového času. Do té doby null.
Name
finished_at
Type
timestamp
Description
Čas, kdy úkol dosáhl konečného stavu, v milisekundách Unixového času. Do té doby null.
Name
expires_at
Type
timestamp
Description
Čas, kdy vyprší platnost výsledku úkolu, v milisekundách Unixového času. Je to 3 dny po finished_at, nebo 3 dny po created_at, dokud úkol neskončí. U Enterprise účtů, které si uchovávají výsledky API neomezeně dlouho, je to přibližně o 100 let později. Viz Uchování assetů.
Name
preceding_tasks
Type
integer
Description
Pozice úkolu ve frontě, dokud má stav PENDING. 1 znamená, že je na řadě jako další. 0 poté, co úkol frontu opustí, a vždy 0 ve výsledcích seznamu.
Name
task_error
Type
object
Description
Důvod selhání úkolu. null, pokud status není FAILED. Viz Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů účtovaných za úkol, po případném vrácení. Požadavek, který vrátí chybu, se neúčtuje. Neúspěšný úkol má hodnotu 0, protože Meshy jej vrátí. Zrušení vrátí kredity za úkol pouze tehdy, pokud je ve stavu PENDING. Pokud Meshy nedokáže přečíst účtovanou částku, odpověď typu get nebo stream toto pole vynechá a požadavek na seznam vrátí 500. V takovém případě požadavek opakujte.
Name
model_urls
Type
object
Description
Odkazy ke stažení 3D modelu, prázdné, dokud úkol není úspěšně dokončen. Úspěšně dokončený úkol má vždy stl a glb má pouze tehdy, pokud Meshy vykreslilo náhled.
- Name
  stl
  Type
  string
  Description
  Odkaz ke stažení souboru STL, což je soubor určený k tisku. Můžete jej otevřít přímo ve slicer.
- Name
  glb
  Type
  string
  Description
  Odkaz ke stažení souboru GLB pro náhled modelu v 3D prohlížeči. Jeho barvy slouží pouze pro náhled. Soubor STL nemá žádnou barvu, takže vytištěný fidget získává svou barvu od filamentu.
  Pokud Meshy nedokáže náhled vykreslit, model_urls neobsahuje klíč glb, takže před jeho čtením ověřte, zda klíč existuje. Úkol se stavem SUCCEEDED má vždy stl.