Creative Lab Fidget Pixel API

Proměňte fotografii ve vícebarevnou, 3D tisknutelnou pixel-art fidget desku ve dvou fázích. Úkol prototypu promění fotografii v pixel-art obrázek. Úkol sestavení pak tento obrázek promění ve vzájemně zapadající díly v jediném souboru 3MF a jako input_task_id používá ID úkolu prototypu.

POST /openapi/creative-lab/fidget-pixel/v1/prototype
POST /openapi/creative-lab/fidget-pixel/v1/build

Oba POST endpointy vyžadují placený tarif. Požadavek z účtu s bezplatným tarifem vrátí 402.

POST/openapi/creative-lab/fidget-pixel/v1/prototype

Create a Fidget Pixel prototype task

Vygeneruje jeden pixel-artový obrázek z fotografie. Pro sestavení dílů předejte ID této úlohy do koncového bodu pro sestavení jako input_task_id. Pole úlohy najdete v Objekt úlohy Fidget Pixel prototype.

Pokud se vám obrázek nelíbí, vytvořte další prototypovou úlohu. Každá úloha je účtována zvlášť.

Request

POST

/openapi/creative-lab/fidget-pixel/v1/prototype

# Stage 1: pixelize the source photo
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype \
  -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>",
    "type": "person"
  }'

Response

{
  "result": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7"
}

Parametry

Name
image_url
Type
string
Povinné
Description
Fotografie, která se má převést na pixel art, jako veřejně dostupná URL adresa nebo data URI (data:image/jpeg;base64,<vaše base64 zakódovaná obrazová data>).
Obrázek musí být soubor JPG, JPEG, PNG nebo WebP o velikosti nejvýše 20 MB. Meshy detekuje formát z obrazových dat, ne z přípony souboru v URL. URL bez přípony funguje a Meshy sleduje přesměrování.
Name
type
Type
string
Povinné
Description
Co fotografie zobrazuje, což určuje styl pixel artu. Oba styly se zřetelně liší. Jakákoli jiná hodnota vrátí 400.
Dostupné hodnoty:
- person: osoba na portrétní nebo celotělové fotografii. Meshy nakreslí pixelový sprite ve stylu chibi.
- other: jakýkoli jiný motiv, například domácí mazlíček, předmět, maskot, logo nebo krajina. Meshy nakreslí pixelovou ikonu ve stylu korálkové mozaiky.
Name
name
Type
string
Description
Název úlohy, nejvýše 100 znaků. Vrátí se v poli name úlohy. Delší název vrátí 400.

Návratové hodnoty

Pole result obsahuje ID nové prototypové úlohy. Získejte úlohu nebo streamujte ji, dokud status nebude SUCCEEDED. Poté předejte ID do koncového bodu pro sestavení jako input_task_id.

Režimy selhání

Name
400 - Bad Request
Description
Požadavek nelze spustit. Například:
- Chybí image_url nebo type.
- type není person ani other.
- 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 stáhnout obrázek, například protože URL vrací 404 nebo vyprší časový limit.
- Data URI není platné 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í jedno z toho:
- Účet nemá dostatek kreditů.
- API klíč, pracovní prostor nebo člen dosáhl svého limitu kreditů.
- Účet má bezplatný plán.
Zkontrolujte své kredity a plán, poté akci zopakujte.
Name
403 - Forbidden
Description
Váš tým má zapnuté IP Filtering a Meshy obrázek označilo kvůli duševnímu vlastnictví třetí strany. Pošlete obrázek, ke kterému máte práva k použ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 úloh čeká ve frontě nebo běží. 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 úloh, které mohou běžet bez kreditů. Počkejte na dokončení úlohy nebo přidejte kredity.
Name
500 - Internal Server Error
Description
Meshy narazilo na chybu serveru, například protože nemohlo na obrázku provést kontrolu duševního vlastnictví. Meshy úlohu nevytvoří a vrátí veškeré účtované kredity. Opakujte požadavek.

POST/openapi/creative-lab/fidget-pixel/v1/build

Vytvoření úlohy sestavení Fidget Pixel

Vygeneruje díly určené k 3D tisku z úspěšně dokončené prototypové úlohy. Meshy namapuje pixel-art obrázek na mřížku a zredukuje jej na nejvýše color_count barev. Z každé buňky subjektu se stane do sebe zapadající díl a pozadí se netiskne.

Výsledkem je jeden vícebarevný soubor 3MF, připravený k barevnému tisku. Každý díl má šedé tělo a horní část v barvě svého pixelu. Popis jeho polí najdete v části Objekt úlohy sestavení Fidget Pixel.

Request

POST

/openapi/creative-lab/fidget-pixel/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "options": {
      "shape": "square",
      "grid_size": 32,
      "piece_size_mm": 8,
      "color_count": 8,
      "piece_height_mm": 15
    },
    "output": {
      "format": "3mf"
    }
  }'

Response

{
  "result": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98"
}

Parametry

Name
input_task_id
Type
string
Povinné
Description
ID prototypové úlohy, která se má sestavit. Musí jít o úlohu vytvořenou vaším účtem pomocí POST /openapi/creative-lab/fidget-pixel/v1/prototype, se stavem SUCCEEDED.
ID, které neodpovídá žádné z vašich prototypových úloh Fidget Pixel z API, vrátí 404, včetně prototypu vytvořeného ve webové aplikaci.
Name
name
Type
string
Description
Název úlohy, maximálně 100 znaků. Vrátí se v poli name úlohy. Delší název vrátí 400.

`options`

Nastavení tvaru a velikosti dílů. Každé pole má výchozí hodnotu, takže pošlete jen ta pole, která chcete změnit. Hodnota 0 použije výchozí hodnotu daného pole. Jde o stejná nastavení jako ve webové aplikaci Creative Lab. Ostatní nastavení tvaru jsou pevně daná a Meshy je nastaví na základě shape a piece_size_mm.

Name
shape
Type
string
výchozí square
Description
Půdorys každého dílu. Jakákoli jiná hodnota vrátí 400.
Dostupné hodnoty:
- square: čtvercové díly na čtvercové mřížce
- hex: šestiúhelníkové díly na šestiúhelníkové mřížce, s piece_size_mm nastaveným na 6 nebo 8
Name
grid_size
Type
integer
výchozí 32
Description
Počet buněk mřížky na každé straně desky, 16 nebo 32. Jakákoli jiná hodnota vrátí 400. Mřížka 32 zachová více detailů. Mřížka 16 dává méně dílů stejné velikosti, takže deska je přibližně poloviční šířky.
Name
piece_size_mm
Type
integer
výchozí 8
Description
Délka hrany každého dílu v milimetrech, 6, 8 nebo 10. Jakákoli jiná hodnota vrátí 400. Spolu s grid_size určuje velikost vytištěné desky. Například mřížka 32 s 8mm díly má přibližně 26,5 cm na stranu.
Hodnota 10 nefunguje s hex a vrací 400, protože šikmá stěna šestiúhelníku na většině spotřebitelských tiskáren FDM přečnívá.
Name
color_count
Type
integer
výchozí 8
Description
Maximální počet barev v pixel-art paletě, od 1 do 8. Hodnota mimo rozsah vrátí 400. K tisku potřebujete až color_count plus jedno vlákno (filament) – jedno na každou barvu a jedno na šedá těla.
Name
piece_height_mm
Type
integer
výchozí 15
Description
Výška každého dílu v milimetrech, od 10 do 80. Hodnota mimo rozsah vrátí 400.

`output`

Nastavení výsledného souboru.

Name
format
Type
string
výchozí 3mf
Description
Formát souboru výsledku. Jakákoli jiná hodnota vrátí 400.
Dostupné hodnoty:
- 3mf: jeden vícebarevný soubor model.3mf, vrácený v model_urls.3mf

Návratové hodnoty

Pole result obsahuje ID nové úlohy sestavení. Získejte úlohu nebo sledujte ji ve streamu, dokud status nebude SUCCEEDED. Poté stáhněte soubor 3MF z model_urls.3mf.

Režimy selhání

Name
400 - Bad Request
Description
Požadavek nelze spustit. Například:
- input_task_id chybí nebo není platné ID úlohy.
- Stav prototypové úlohy není SUCCEEDED. Pokud stále běží, počkejte a zkuste to znovu. Pokud selhala nebo byla zrušena, vytvořte novou prototypovou úlohu.
- Prototypová úloha byla úspěšná, ale neobsahuje žádný obrázek. Vytvořte novou prototypovou úlohu.
- Pole options je mimo povolené hodnoty, například grid_size jiné než 16 nebo 32.
- piece_size_mm je 10 a shape je hex. Šestiúhelníkové díly existují pouze ve velikosti 6 a 8 mm.
- output.format není 3mf.
Chybová zpráva uvádí, jaký problém byl nalezen.
Name
401 - Unauthorized
Description
API klíč chybí nebo je neplatný. Zkontrolujte hlavičku Authorization.
Name
402 - Payment Required
Description
Platí jedno z následujícího:
- Účet nemá dostatek kreditů.
- API klíč, pracovní prostor nebo člen dosáhl svého limitu kreditů.
- Účet má bezplatný plán.
Zkontrolujte své kredity a plán a zkuste to znovu.
Name
403 - Forbidden
Description
Váš tým má zapnuté filtrování IP adres a Meshy označilo obrázek prototypové úlohy jako obsahující duševní vlastnictví třetí strany. Vytvořte prototypovou úlohu z obrázku, ke kterému máte práva k použití.
Name
404 - Not Found
Description
input_task_id neodpovídá žádné prototypové úloze Fidget Pixel, kterou váš účet vytvořil přes API. Prototyp vytvořený ve webové aplikaci rovněž vrátí 404. Pošlete ID result z odpovědi na vytvoření prototypu.
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 úloh je ve frontě nebo běží. Počkejte, až se některé dokončí, a zkuste to znovu.
- Na neomezeném plánu bez zbývajících kreditů jste dosáhli počtu úloh, které mohou běžet bez kreditů. Počkejte na dokončení úlohy, nebo přidejte kredity.
Name
500 - Internal Server Error
Description
Meshy narazilo na chybu serveru, například protože nebylo možné spustit kontrolu duševního vlastnictví na obrázku prototypové úlohy. Meshy úlohu nevytvoří a vrátí veškeré účtované kredity. Zkuste požadavek odeslat znovu.

GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id

Získání úlohy Fidget Pixel

Vrátí úlohu typu prototyp nebo build. Cesta musí odpovídat fázi úlohy. Úloha typu build vyžádaná přes /prototype/:id vrátí 404, a totéž platí pro úlohu typu prototyp vyžádanou přes /build/:id.

Informace o polích najdete v Objekt úlohy prototypu Fidget Pixel a Objekt úlohy buildu Fidget Pixel.

Request

GET

/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
  ]
}

Build Response

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Parametry

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

Návratová hodnota

Objekt úlohy prototypu nebo objekt úlohy buildu, podle fáze uvedené v cestě.

Způsoby selhání

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é IP Filtering a Meshy označilo obrázek úlohy prototypu kvůli duševnímu vlastnictví třetí strany. U úloh typu build a u týmů v plánu Enterprise se tato chyba nevyskytuje. Vytvořte úlohu prototypu z obrázku, ke kterému máte práva k užívání.
Name
404 - Not Found
Description
Žádná úloha Fidget Pixel s tímto ID nepatří k vašemu účtu, nebo fáze úlohy neodpovídá cestě. Zkontrolujte ID a použijte /prototype nebo /build podle typu úlohy.
Name
500 - Internal Server Error
Description
Meshy nemohlo provést kontrolu duševního vlastnictví. Zopakujte požadavek.

DELETE/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id

Smazání úlohy Fidget Pixel

Zruší úlohu Fidget Pixel. 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.

Cesta musí odpovídat fázi úlohy. Například DELETE na /prototype/:id s ID úlohy build vrátí 404.

Request

DELETE

/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -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.

Režimy selhání

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 už má konečný stav (SUCCEEDED, FAILED nebo CANCELED), takže ji nelze zrušit.
Name
404 - Not Found
Description
Žádná úloha Fidget Pixel s tímto ID nepatří k vašemu účtu, nebo fáze úlohy neodpovídá cestě. Zkontrolujte ID a použijte /prototype nebo /build tak, aby odpovídalo dané úloze.

GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id/stream

Streamování úlohy Fidget Pixel

Streamuje aktualizace úlohy Fidget Pixel jako Server-Sent Events (SSE). Cesta musí odpovídat fázi úlohy. Pokud neodpovídá, například pokud je ID build úlohy použito na /prototype/:id/stream, stream odešle jednu událost error se status_code: 404 a uzavře se. id, které není platným ID úlohy, způsobí totéž se status_code: 400.

Request

GET

/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object for the stage; fields not yet populated are null / empty.
event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "PENDING",
  "progress": 0,
  "created_at": 1757001300000,
  "started_at": null,
  "finished_at": null,
  "expires_at": 1757260500000,
  "preceding_tasks": 2,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {}
}

event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Parametry

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

Návratová hodnota

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

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

GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)

Seznam úloh Fidget Pixel

Vrátí vaše úlohy Fidget Pixel pro jednu fázi, vždy po jedné stránce. Cesta určuje fázi. /prototype vrací pouze prototypové úlohy a /build vrací pouze úlohy sestavení.

Request

GET

/openapi/creative-lab/fidget-pixel/v1/prototype

# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "type": "creative-lab-fidget-pixel-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1757001000000,
    "started_at": 1757001005000,
    "finished_at": 1757001178000,
    "expires_at": 1757260378000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
    ]
  }
]

Parametry cesty

Name
stage
Type
path
Povinné
Description
Fáze, kterou chcete vypsat, prototype nebo build.

Parametry dotazu

Name
page_num
Type
integer
výchozí 1
Description
Stránka, která se má vrátit, od 1 do 255. Hodnota 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, maximálně 100. Hodnota od 101 do 255 vrátí 100 úloh a hodnota 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ů prototypové úlohy nebo objektů úlohy sestavení, odpovídající fázi uvedené v cestě.

Objekt úkolu prototypu Fidget Pixel

Úkol prototypu přemění fotografii na pixel-art obrázek. Chcete-li obrázek přeměnit na 3D tisknutelné díly, předejte ID úkolu do build koncového bodu jako input_task_id.

Vlastnosti

Example Fidget Pixel Prototype Task Object

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?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-pixel-prototype.
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ž uspěje.
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 spustil, 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 podnikových (Enterprise) účtů, které 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ě, pokud je PENDING. 1 znamená, že začne jako další. 0 poté, co úkol opustí frontu, 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í zpě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 zopakujte.
Name
image_urls
Type
array of strings
Description
URL adresy pro stažení pixel-art obrázku. Pole obsahuje jednu URL adresu poté, co úkol uspěje, a do té doby je prázdné.
URL adresy jsou podepsané, takže je načítejte bez hlavičky Authorization. Zůstávají platné až do expires_at. Opětovné získání úkolu před tímto časem vrátí stejné URL adresy, nikoli nově podepsané. Platnost vypršelé URL adresy nelze obnovit, proto soubory stáhněte a uložte dříve.

Objekt build úlohy Fidget Pixel

Build úloha vygeneruje 3D-tisknutelné díly z úspěšné prototype úlohy. Meshy namapuje pixel-art obrázek na mřížku a vrátí díly v jediném vícebarevném souboru 3MF.

Vlastnosti

Example Fidget Pixel Build Task Object

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Name
id
Type
string
Description
ID úlohy. Nespoléhejte na jeho formát.
Name
type
Type
string
Description
Typ úlohy, vždy creative-lab-fidget-pixel-build.
Name
name
Type
string
Description
name, který jste odeslali při vytvoření úlohy, nebo "", pokud jste žádný neodeslali.
Name
status
Type
string
Description
Stav úlohy.
Dostupné hodnoty:
- PENDING: čeká ve frontě
- IN_PROGRESS: generuje se výsledek
- SUCCEEDED: finální, s výsledkem
- FAILED: finální, s důvodem v task_error
- CANCELED: finální, bez výsledku
Name
progress
Type
integer
Description
Procento dokončené práce, od 0 do 100. Je 0, dokud úloha nezačne, a 100, když uspěje.
Name
created_at
Type
timestamp
Description
Čas vytvoření úlohy, v milisekundách unixového času.
Name
started_at
Type
timestamp
Description
Čas, kdy worker úlohu spustil, v milisekundách unixového času. Do té doby null.
Name
finished_at
Type
timestamp
Description
Čas, kdy úloha dosáhla finálního stavu, v milisekundách unixového času. Do té doby null.
Name
expires_at
Type
timestamp
Description
Čas, kdy vyprší výsledek úlohy, v milisekundách unixového času. Je to 3 dny po finished_at, nebo 3 dny po created_at, dokud úloha neskončí. U Enterprise účtů, které 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 úlohy ve frontě, dokud je PENDING. 1 znamená, že začne jako další. 0 poté, co úloha opustí frontu, a vždy 0 ve výsledcích seznamu.
Name
task_error
Type
object
Description
Důvod, proč úloha selhala. null, pokud status není FAILED. Viz Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů účtovaných za úlohu, po případném vrácení. Požadavek, který vrátí chybu, není zpoplatněn. Neúspěšná úloha má hodnotu 0, protože Meshy ji vrátí. Zrušení vrátí kredity za úlohu pouze tehdy, je-li ve stavu PENDING. Pokud Meshy nedokáže zjistit poplatek, odpověď na get nebo stream toto pole vynechá a požadavek na seznam vrátí 500. V takovém případě požadavek zopakujte.
Name
model_urls
Type
object
Description
Adresy URL ke stažení výsledku, klíčované podle formátu souboru. Objekt obsahuje jednu položku, pro output.format, který jste odeslali, a je prázdný, dokud úloha neuspěje.
Adresy URL jsou podepsané, takže je načítejte bez hlavičky Authorization. Zůstávají platné až do expires_at. Opětovné získání úlohy před touto dobou vrátí stejné adresy URL, nikoli nově podepsané. Vypršenou adresu URL nelze obnovit, proto si soubory stáhněte a uložte dříve.
- Name
  3mf
  Type
  string
  Description
  Adresa URL ke stažení vícebarevného souboru 3MF. Každý díl má šedé tělo a horní část v barvě svého pixelu. Přítomno, když je output.format roven 3mf, což je výchozí hodnota.

Kompletní příklad od začátku do konce

Následující skripty v cURL a Pythonu spouští celý postup. Každý skript vytvoří úlohu prototypu z fotografie a počká, až skončí úspěchem. Poté vytvoří stavební úlohu, počká na její dokončení a stáhne soubor 3MF z model_urls.3mf.

Skript v cURL vyžaduje curl a jq, skript v Pythonu vyžaduje balíček requests. Chcete-li spustit skript, postupujte takto:

Nastavte MESHY_API_KEY na svůj API klíč.
Nastavte IMAGE_PATH na cestu k místní fotografii, nebo IMAGE_URL na veřejnou URL adresu obrázku.
Volitelné: Chcete-li pixelizovat jiný objekt než osobu, nastavte PIXEL_TYPE na other.
Spusťte skript.

Úloha prototypu obvykle skončí během několika minut. Stavební úloha obvykle skončí za podstatně méně než minutu.

Ve své aplikaci zobrazte uživateli obrázek z image_urls ještě předtím, než vytvoříte stavební úlohu. Pokud se mu nelíbí, vytvořte místo toho další úlohu prototypu. Tímto způsobem utratíte kredity za sestavení pouze za obrázek, který uživatel schválí.

Complete flow

POST

/openapi/creative-lab/fidget-pixel/v1

#!/usr/bin/env bash
set -euo pipefail

# Requires curl and jq. Point IMAGE_PATH at a local photo, or IMAGE_URL at a public one:
#   export MESHY_API_KEY=msy_...
#   export IMAGE_PATH=./portrait.jpg          # or: export IMAGE_URL=https://...
#   export PIXEL_TYPE=person                  # or: other
: "${MESHY_API_KEY:?export MESHY_API_KEY first}"
if [[ -z "${IMAGE_PATH:-}" && -z "${IMAGE_URL:-}" ]]; then
  echo "export IMAGE_PATH (local file) or IMAGE_URL (public url) first" >&2
  exit 1
fi
PIXEL_TYPE=${PIXEL_TYPE:-person}

BASE="https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1"
AUTH="Authorization: Bearer $MESHY_API_KEY"

# api METHOD URL [curl args...] -> prints the response body, non-zero on failure.
# Note we do not use -f/--fail: it discards the body, and the body is the only
# place the reason appears.
api() {
  local method=$1 url=$2 out http_code body
  shift 2
  out=$(curl --silent --show-error --max-time 60 --write-out $'\n%{http_code}' \
    -X "$method" "$url" -H "$AUTH" "$@") || return 1
  http_code=${out##*$'\n'}
  body=${out%$'\n'*}
  if ((http_code >= 400)); then
    echo "HTTP $http_code for $url: $body" >&2
    return 1
  fi
  printf '%s' "$body"
}

# Each task gets its own 40-minute budget.
poll() {
  local kind=$1 id=$2 delay=5 task_status deadline
  deadline=$(($(date +%s) + 2400))
  while :; do
    if (($(date +%s) >= deadline)); then
      echo "gave up waiting for $kind $id" >&2
      return 1
    fi
    task_status=$(api GET "$BASE/$kind/$id" | jq -r '.status')
    echo "$kind: $task_status"
    case "$task_status" in
    SUCCEEDED) return 0 ;;
    FAILED | CANCELED) return 1 ;;
    esac
    sleep "$delay"
    delay=$((delay * 2 > 30 ? 30 : delay * 2))
  done
}

# Build the request body in a file. A base64 data URI must never go on the
# command line or into an exported variable - a photo of any real size will
# exceed the OS argument limit.
BODY=$(mktemp)
trap 'rm -f "$BODY"' EXIT
if [[ -n "${IMAGE_PATH:-}" ]]; then
  # Declare the real type: the API accepts JPEG, PNG and WebP.
  case "$(printf '%s' "${IMAGE_PATH##*.}" | tr 'A-Z' 'a-z')" in
    png) MIME=image/png ;;
    webp) MIME=image/webp ;;
    *) MIME=image/jpeg ;;
  esac
  {
    printf '{"type":"%s","image_url":"data:%s;base64,' "$PIXEL_TYPE" "$MIME"
    base64 <"$IMAGE_PATH" | tr -d '\n'
    printf '"}'
  } >"$BODY"
else
  jq -n --arg t "$PIXEL_TYPE" --arg u "$IMAGE_URL" \
    '{type: $t, image_url: $u}' >"$BODY"
fi

# 1. Create the prototype task
PROTO_ID=$(api POST "$BASE/prototype" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 2. Wait for the pixel-art image (show image_urls[0] to a user in production)
poll prototype "$PROTO_ID"

# 3. Create the build task (defaults: square pieces, 32x32 grid, 8 mm, 8 colors, 15 mm tall)
jq -n --arg p "$PROTO_ID" \
  '{input_task_id: $p, options: {shape: "square", grid_size: 32, piece_size_mm: 8, color_count: 8, piece_height_mm: 15}, output: {format: "3mf"}}' >"$BODY"
BUILD_ID=$(api POST "$BASE/build" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 4. Wait for the pieces
poll build "$BUILD_ID"

# 5. Download the 3MF. This is a signed URL: no Authorization header,
#    and it stays valid for 3 days after the task finishes.
TASK=$(api GET "$BASE/build/$BUILD_ID")
curl --silent --show-error --fail --max-time 900 \
  -o fidget-pixel.3mf "$(jq -r '.model_urls["3mf"]' <<<"$TASK")"
echo "Done: fidget-pixel.3mf"