Creative Lab — API pro skládací fidget

Proměňte zdrojovou fotografii ve skládací fidget hračku připravenou k tisku: silueta objektu se stane sadou vnořených soustředných kruhů, které se dají složit naplocho a znovu roztáhnout, vytištěnou v jednom kuse bez montáže.

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

Na rozdíl od ostatních endpointů Creative Lab nemá tento žádnou 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ž ke 3D modelu. Ani ovládací prvky geometrie, které webová aplikace zpřístupňuje (velikost, počet vrstev, šířka mezery, tloušťka stěny, hloubka vytlačení, 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

Vygeneruje model skládacího fidgetu ze zdrojové fotografie. Informace o tvaru odpovědi najdete 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časné době podporujeme formáty .jpg, .jpeg, .png a .webp.

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

    • Veřejně dostupná URL: URL adresa dostupná 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 předmět s jedním jasným, uzavřeným obrysem — právě silueta se stává prstenci. Rušná pozadí, více samostatných předmětů nebo velmi tenké tvary mohou zanechat 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ů. Jde pouze o popisek úlohy; na model se nic nevyrývá.

Návratové hodnoty

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

Režimy selhání

  • Name
    400 - Bad Request
    Description

    Požadavek byl nepřijatelný. Časté příčiny:

    • Chybějící parametr: image_url je povinný.
    • Neplatný formát obrázku: Zadaný 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: image_url se nepodařilo stáhnout (404 nebo timeout).
    • Neplatné Data URI: Base64 řetězec je poškozený.
    • Obsah 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 na tomto koncovém 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 svůj 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 skládacího fidgetu

Získejte úlohu skládacího fidgetu 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 skládacího fidgetu.

Parametry

  • Name
    id
    Type
    path
    Description

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

Návratová hodnota

Odpověď obsahuje objekt úlohy skládacího fidgetu.

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

Odstranění úlohy Collapsible Fidget

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

Path Parameters

  • Name
    id
    Type
    path
    Description

    Jedinečný identifikátor úlohy collapsible fidget, kterou chcete zrušit.

Returns

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

Failure Modes

  • Name
    400 - Bad Request
    Description

    Úloha je již 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 přes tento koncový bod.

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 úlohy skládacího fidgetu v reálném čase pomocí Server-Sent Events (SSE). Úloha, která neexistuje nebo nebyla vytvořena přes tento koncový bod, vyšle jediný event: error payload se status_code: 404 a stream ukončí.

Parametry

  • Name
    id
    Type
    path
    Description

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

Návratové hodnoty

Vrací stream objektů úloh Skládacího fidgetu ve formě Server-Sent Events. U úloh se stavem PENDING nebo IN_PROGRESS bude stream odpovědi obsahovat pouze nezbytná pole progress a status.

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

Seznam úkolů skládacího fidgetu

Získejte stránkovaný seznam vašich úkolů skládacího fidgetu. Zahrnuty jsou pouze úkoly 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: Řadit podle času vytvoření vzestupně.
    • -created_at: Řadit podle času vytvoření sestupně.

Návratová hodnota

Vrací stránkovaný seznam objektů úkolu skládacího fidgetu.

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 skládacího fidgetu

Objekt úlohy skládacího fidgetu je pracovní jednotka, kterou Meshy sleduje při převodu zdrojové fotografie na tiskový model skládacího fidgetu určeného k tisku bez nutnosti montáže. Jedná se o jednostupňovou úlohu: neexistuje žádný prototyp, ze kterého by se navazovalo, a mezilehlá 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 úlohy k-seřaditelné 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 zadán žádný název.

  • 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 úlohy (progress). Pokud úloha ještě nebyla zahájena, tato vlastnost bude 0. Jakmile úloha uspěje, 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 uplynulých od 1. ledna 1970 UTC podle standardu RFC 3339. Například pátek 1. září 2023 12:00:00 GMT je reprezentován 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, tato vlastnost bude null.

  • Name
    finished_at
    Type
    timestamp
    Description

    Časové razítko dokončení úlohy, v milisekundách. Pokud úloha ještě nebyla dokončena, tato vlastnost bude 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 v případě, že je stav úlohy PENDING.

  • Name
    task_error
    Type
    object
    Description

    Podrobnosti o chybě u neúspěšných úloh. Úplný odkaz na objekt task_error najdete v části 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 selhání vráceny).

  • Name
    model_urls
    Type
    object
    Description

    Odkazy ke stažení vygenerovaného 3D modelu. Naplní se po dosažení stavu SUCCEEDED: stl je vždy přítomen, glb pouze pokud se náhledové vykreslení podařilo.

    • Name
      stl
      Type
      string
      Description

      Odkaz ke stažení souboru STL. Toto je tisknutelný výstup — pošlete jej přímo do 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: STL neobsahuje žádnou barvu a vytištěný fidget získává barvu z filamentu. GLB je poskytován na nejlepší možné úrovni: pokud náhledové vykreslení není k dispozici, klíč je z model_urls zcela vynechán, takže jej čtěte defenzivně — stl je výstupem a je vždy přítomen u úlohy se stavem 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.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=***"
  }
}