Creative Lab — Keychain API

Přeměňte zdrojovou fotografii na 3D tisknutelný medailon klíčenky — odznakový barevný hloubkový reliéf — ve dvou fázích: prototype vygeneruje barevný koncepční obrázek z vaší vstupní fotografie, poté build promění tento koncepční obrázek na reliéfní 3D model. Obě fáze jsou propojeny pomocí input_task_id.

  • POST /openapi/creative-lab/keychain/v1/prototype
  • POST /openapi/creative-lab/keychain/v1/build
POST/openapi/creative-lab/keychain/v1/prototype

Vytvoření úkolu Keychain Prototype

Vygeneruje jeden obarvený koncepční obrázek ze zdrojové fotografie. Vrácené ID úkolu je hodnota, kterou předáte jako input_task_id koncovému bodu pro sestavení (build). Podobu odpovědi najdete v sekci Objekt úkolu Keychain Prototype.

Parametry

  • Name
    image_url
    Type
    string
    Povinné
    Description

    Zdrojová fotografie, kterou Meshy obarví do koncepčního obrázku připraveného pro klíčenku. Aktuálně podporujeme formáty .jpg, .jpeg, .png a .webp.

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

    • Veřejně přístupná 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 zakódovaná data obrázku>.
  • Name
    name
    Type
    string
    Description

    Volitelný název úkolu pro zobrazovací účely. Maximálně 100 znaků.

    Tento název označuje úkol ve vašem dashboardu a seznamech úkolů. Není vyrytý na klíčence — k tomu slouží name_text.

  • Name
    name_text
    Type
    string
    Description

    Text, který se má vyrýt na klíčenku, například jméno mazlíčka nebo osoby. Maximálně 10 znaků, počítáno jako Unicode znaky, nikoli bajty, takže je přijatelné i 10znakové čínské, japonské nebo korejské jméno. Ponecháte-li pole prázdné, vznikne klíčenka bez rytiny.

    Před použitím textu se odstraní okolní bílé znaky a neviditelné formátovací znaky. Výsledná hodnota se vrací jako name_text v objektu úkolu prototypu, takže si můžete ověřit, co přesně bude vyryto, ještě před zaplacením fáze sestavení.

    Rytina se vytváří zde, ve fázi prototypu. Fáze sestavení ji automaticky přebírá a vlastní parametr name_text nepřijímá.

    Pokud text není čistě ASCII, odešlete tělo požadavku jako UTF-8 a nastavte Content-Type: application/json; charset=utf-8. Některé HTTP klienty — mimo jiné Invoke-RestMethod z Windows PowerShellu — kódují tělo požadavku ve výchozím nastavení jako ISO-8859-1, což tiše promění každý nelatinský znak na ? ještě předtím, než se dostane k Meshy. API pak nedokáže rozlišit, zda jde o skutečně požadovanou rytinu.

  • Name
    remove_background
    Type
    boolean
    výchozí false
    Description

    Pokud je nastaveno na true, vrátí se prototypový obrázek jako transparentní RGBA PNG s odstraněným pozadím, abyste mohli objekt umístit na libovolné pozadí.

    Toto nastavení ovlivňuje pouze obrázek vrácený tímto koncovým bodem. Je nezávislé na stejnojmenné volbě v rámci sestavení (výchozí hodnota true), která řídí odstranění pozadí před reliéfováním.

Návratové hodnoty

Vlastnost result odpovědi obsahuje id nově vytvořeného úkolu Keychain Prototype. Dotazujte se na koncový bod Get a Task nebo se přihlaste k odběru streamu, dokud úkol nedosáhne stavu SUCCEEDED, a poté toto ID předejte koncovému bodu pro sestavení jako input_task_id.

Chybové stavy

  • 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 povolený 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 (chyba 404 nebo timeout).
    • Neplatné Data URI: Base64 řetězec je poškozený.
    • Příliš dlouhá rytina: name_text je delší než 10 znaků. Požadavek je v takovém případě odmítnut, nikoli zkrácen, takže vám nikdy nebude účtována klíčenka s rytinou zkráceného jména.
    • Označený obsah: Vstupní obrázek byl označen moderací obsahu pro nevhodný (NSFW) obsah nebo porušení duševního vlastnictví, případně rytina name_text byla označena moderací nevhodného (NSFW) obsahu. Rytina je kontrolována pouze na nevhodný obsah — kontrola duševního vlastnictví se týká obrázku.
  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

    Nedostatek kreditů k provedení tohoto úkolu.

  • Name
    429 - Too Many Requests
    Description

    Překročili jste limit rychlosti.

Request

POST
/openapi/creative-lab/keychain/v1/prototype
# Stage 1: generate a colorized keychain concept image
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "name_text": "Luna"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Prototype example
Start with a source photo, then generate the prototype image used by the keychain build stage.
Source photo used as the Creative Lab Keychain input
Prototype input
Creative Lab Keychain prototype output generated from the source photo
Prototype output
POST/openapi/creative-lab/keychain/v1/build

Vytvořit úlohu sestavení klíčenky

Vygeneruje finální 3D tisknutelný medailon klíčenky z úspěšné úlohy prototypu. Sestavení spustí pipeline reliéfu z mapy hloubky na obarveném koncepčním obrázku prototypu a odešle jediný artefakt sítě ve formátu, který požadujete. Podobu odpovědi naleznete v části Objekt úlohy sestavení klíčenky.

Parametry

  • Name
    input_task_id
    Type
    string
    Povinné
    Description

    ID úlohy prototypu vytvořené přes tentýž koncový bod OpenAPI. Prototyp musí být vytvořen se stejným API klíčem, musí dosáhnout stavu SUCCEEDED a musí vygenerovat přesně jeden kandidátský obrázek.

    Úlohy prototypu vytvořené přes webovou aplikaci nejsou přijímány — koncový bod sestavení přijímá pouze úlohy prototypu vytvořené pomocí POST /openapi/creative-lab/keychain/v1/prototype a jakýkoli jiný zdroj odmítne s 404.

  • Name
    name
    Type
    string
    Description

    Volitelný název úlohy pro zobrazení. Maximálně 100 znaků.

options

Volitelné parametry ladění geometrie reliéfu. Každé pole má rozumnou výchozí hodnotu — odešlete pouze ty, které chcete přepsat.

  • Name
    badge_shape
    Type
    string
    výchozí circle
    Description

    Obrysová silueta medailonu klíčenky. Dostupné hodnoty:

    • circle (výchozí)
    • rounded-rect
    • hexagon
    • shield
    • star
  • Name
    size_mm
    Type
    number
    výchozí 40
    Description

    Délka hrany ohraničujícího čtverce klíčenky v milimetrech. Rozsah: (0, 400].

  • Name
    relief_height_mm
    Type
    number
    výchozí 2.2
    Description

    Maximální výška reliéfu nad základnou, v milimetrech. Rozsah: [0, 20].

  • Name
    relief_offset_mm
    Type
    number
    výchozí 0
    Description

    Svislý posun aplikovaný na reliéf před vysunutím (extruzí), v milimetrech. Rozsah: [0, 20].

  • Name
    base_thickness_mm
    Type
    number
    výchozí 0.1
    Description

    Tloušťka rovné základní desky za reliéfem, v milimetrech. Rozsah: [0, 20].

  • Name
    has_closed_back
    Type
    boolean
    výchozí true
    Description

    Zda je zadní strana medailonu uzavřena jako plná plocha. Nastavte na false pro otevřenou skořepinu.

  • Name
    relief_curve
    Type
    string
    výchozí linear
    Description

    Přenosová křivka mapující hodnoty mapy hloubky na výšku reliéfu. Dostupné hodnoty:

    • linear (výchozí)
    • gamma
    • s-curve
  • Name
    curve_param
    Type
    number
    výchozí 1.0
    Description

    Parametr tvaru přenosové křivky (má význam pouze pokud je relief_curve nastaveno na gamma). Rozsah: (0, 10].

  • Name
    invert_depth
    Type
    boolean
    výchozí false
    Description

    Invertuje interpretaci mapy hloubky tak, že tmavší oblasti se stanou vyšším reliéfem.

  • Name
    smoothing
    Type
    number
    výchozí 0.24
    Description

    Síla vyhlazení aplikovaná na mapu hloubky před extrakcí reliéfu. Rozsah: [0, 10].

  • Name
    relief_scale
    Type
    number
    výchozí 1.0
    Description

    Násobitel svislého měřítka aplikovaný nad rámec relief_height_mm. Rozsah: (0, 10].

  • Name
    depth_threshold
    Type
    number
    výchozí 0.1
    Description

    Práh dolní propusti pro hodnoty mapy hloubky; vše pod touto hodnotou je oříznuto na nulu. Rozsah: [0, 1].

  • Name
    remove_background
    Type
    boolean
    výchozí true
    Description

    Automaticky odstraní pozadí koncepčního obrázku prototypu před vytvořením reliéfu.

    Odlišné od stejnojmenného parametru prototypu (výchozí hodnota false), který určuje, zda je samotný obrázek prototypu vrácen s průhledností.

  • Name
    export_resolution
    Type
    integer
    výchozí 512
    Description

    Rozlišení sítě použité pro export. Rozsah: [64, 2048].

output

Volitelný selektor výstupního formátu. Výchozí hodnota je glb.

  • Name
    format
    Type
    string
    výchozí glb
    Description

    Balíček artefaktů vrácený sestavením. Dostupné hodnoty:

    • glb (výchozí) — vrátí jediný soubor model.glb v model_urls.glb.
    • obj — zabalí model.obj + model.mtl + texture.png a vrátí balíček v model_urls.obj.
    • zip — zabalí každý artefakt vygenerovaný generátorem a vrátí balíček v model_urls.bundle_zip.

Návratová hodnota

Vlastnost result odpovědi obsahuje id úlohy nově vytvořené úlohy sestavení klíčenky. 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 artefakt z jediné položky v model_urls.

Režimy selhání

  • Name
    400 - Bad Request
    Description

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

    • Chybějící parametr: input_task_id je povinný.
    • Neplatné UUID: input_task_id není platné UUID.
    • Nadřazená úloha nedokončena úspěšně: Odkazovaná úloha prototypu ještě nedosáhla stavu SUCCEEDED.
    • Žádný kandidát: Úloha prototypu byla úspěšná, ale nevygenerovala žádný kandidátský obrázek.
    • Volby mimo rozsah: Jedno z polí options bylo mimo povolený rozsah nebo výčtovou sadu.
  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

    Nedostatek kreditů k provedení této úlohy.

  • Name
    404 - Not Found
    Description

    Odkazovaná úloha prototypu neexistuje, patří jinému uživateli nebo byla vytvořena přes webovou aplikaci (do sestavení lze navázat pouze úlohy prototypu vytvořené v režimu API).

  • Name
    429 - Too Many Requests
    Description

    Překročili jste svůj limit rychlosti.

Request

POST
/openapi/creative-lab/keychain/v1/build
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "options": {
      "badge_shape": "circle",
      "size_mm": 40,
      "relief_height_mm": 2.5
    },
    "output": {
      "format": "glb"
    }
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}
Build example
Úloha sestavení převede vybraný obrázek prototypu na 3D tisknutelný model klíčenky.
Creative Lab Keychain build model preview
Build model preview
GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id

Načtení úlohy klíčenky

Načte úlohu prototypu nebo sestavení podle platného id úlohy. Cesta URL musí odpovídat fázi úlohy — úloha sestavení načtená přes /prototype/:id vrátí 404, a naopak.

Podrobnosti o tvaru odpovědi najdete v Objekt úlohy prototypu klíčenky a Objekt úlohy sestavení klíčenky.

Parametry

  • Name
    id
    Type
    path
    Description

    Unikátní identifikátor úlohy klíčenky, kterou chcete načíst.

Návratová hodnota

Odpověď obsahuje objekt úlohy klíčenky. Tvar odpovědi závisí na tom, která fáze byla požadována.

Request

GET
/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}
DELETE/openapi/creative-lab/keychain/v1/(prototype|build)/:id

Delete a Keychain Task

Zruší úlohu klíčenky. 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 již může spotřebovávat zdroje). Úlohy, které již dosáhly konečného stavu (SUCCEEDED, FAILED, CANCELED), nelze zrušit.

Cesta URL musí odpovídat fázi úlohy — DELETE na /prototype/:buildId vrátí 404.

Parametry cesty

  • Name
    id
    Type
    path
    Description

    Jedinečný identifikátor úlohy klíčenky, 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 je již v konečném stavu a nelze ji zrušit.

  • Name
    404 - Not Found
    Description

    Úloha neexistuje, patří jinému uživateli, nebo její fáze neodpovídá cestě URL.

Request

DELETE
/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).
GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id/stream

Streamování úlohy klíčenky

Streamujte aktualizace úlohy klíčenky v reálném čase pomocí Server-Sent Events (SSE). Cesta URL musí odpovídat fázi úlohy — otevření streamu na /prototype/:buildId/stream vyvolá jediný payload event: error s status_code: 404 a stream se uzavře.

Parametry

  • Name
    id
    Type
    path
    Description

    Jedinečný identifikátor úlohy klíčenky, kterou chcete streamovat.

Návratová hodnota

Vrací stream objektů úlohy Keychain Prototype nebo Keychain Build ve formě Server-Sent Events. Každý snímek nese kompletní objekt úlohy pro danou fázi — stejnou strukturu, jakou vrací koncový bod Get — takže dokud je úloha ve stavu PENDING nebo IN_PROGRESS, výstupní pole jednoduše ještě nejsou vyplněna (null, [] nebo {}) a finished_at je null.

Request

GET
/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream
curl -N https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/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; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}
GET/openapi/creative-lab/keychain/v1/(prototype|build)

List Keychain Tasks

Získejte stránkovaný seznam vašich úkolů klíčenky pro jednu fázi. Cesta URL určuje fázi — /prototype vrací úkoly prototypu; /build vrací úkoly sestavení. Úkoly z druhé fáze nejsou zahrnuty v žádné z odpovědí.

Path Parameters

  • Name
    stage
    Type
    path
    Povinné
    Description

    Buď prototype, nebo build. Kolekce vrací pouze úkoly, jejichž fáze odpovídá adrese URL — načtení /prototype nikdy nevrátí úkoly sestavení a naopak.

Query Parameters

  • 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: Řazení podle času vytvoření vzestupně.
    • -created_at: Řazení podle času vytvoření sestupně.

Returns

Vrací stránkovaný seznam objektu úkolu pro danou fázi — buď objekt úkolu prototypu klíčenky, pokud vypisujete /prototype, nebo objekt úkolu sestavení klíčenky, pokud vypisujete /build.

Request

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

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

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-keychain-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

Objekt úkolu Keychain Prototype

Objekt Keychain Prototype Task je jednotka práce, kterou Meshy sleduje za účelem vygenerování barevného konceptuálního obrázku ze zdrojové fotografie. Výstup této fáze je zřetězen do fáze sestavení pomocí input_task_id.

Vlastnosti

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    Typ úkolu. Hodnota je creative-lab-keychain-prototype.

  • Name
    name
    Type
    string
    Description

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

  • Name
    name_text
    Type
    string
    Description

    Gravírovaný text aplikovaný na tuto klíčenku, po odstranění mezer a neviditelných formátovacích znaků. Chybí, pokud byl úkol vytvořen bez name_text. Porovnejte jej s tím, co jste odeslali, abyste potvrdili, že text přežil kódování vašeho HTTP klienta.

  • Name
    status
    Type
    string
    Description

    Stav úkolu. Možné hodnoty jsou jedna z PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progress úkolu. Pokud úkol ještě nebyl zahájen, tato vlastnost bude 0. Jakmile úkol uspěje, stane se 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Časové razítko, kdy byl úkol vytvořen, 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 PM GMT je vyjádřen jako 1693569600000. To platí pro všechna časová razítka v Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Časové razítko, kdy byl úkol zahájen, v milisekundách. Pokud úkol ještě nebyl zahájen, tato vlastnost bude 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Časové razítko, kdy byl úkol dokončen, v milisekundách. Pokud úkol ještě není dokončen, tato vlastnost bude 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Časové razítko, kdy vyprší výsledek úkolu, v milisekundách.

  • Name
    preceding_tasks
    Type
    integer
    Description

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

    Hodnota tohoto pole má smysl pouze tehdy, pokud je stav úkolu PENDING.

  • Name
    task_error
    Type
    object
    Description

    Podrobnosti o chybě u neúspěšných úkolů. Úplnou referenci objektu task_error najdete v části Chyby.

  • Name
    consumed_credits
    Type
    integer
    Description

    Počet kreditů spotřebovaných tímto úkolem. Přítomno, pokud je stav úkolu PENDING, IN_PROGRESS nebo SUCCEEDED. Vrací 0 u úkolů se stavem FAILED (kredity jsou při neúspěchu vráceny).

  • Name
    image_urls
    Type
    array of strings
    Description

    Stažitelné URL adresy pro kandidáty konceptuálního obrázku vygenerované tímto prototypovým úkolem. V současné době API vždy vrací přesně jednoho kandidáta; pole je typu array, aby budoucí revize mohly nabídnout více kandidátů bez přerušující změny.

Example Keychain Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "name_text": "Luna",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Objekt Build Task pro klíčenku

Objekt Build Task pro klíčenku je pracovní jednotka, kterou Meshy sleduje za účelem vygenerování finální 3D sítě klíčenky z úspěšné prototypové úlohy. Build spouští pipeline reliéfu z mapy hloubky nad koncepčním obrázkem prototypu a publikuje jeden artefakt sítě ve formátu požadovaném volajícím.

Vlastnosti

  • Name
    id
    Type
    string
    Description

    Jedinečný identifikátor úlohy.

  • Name
    type
    Type
    string
    Description

    Typ úlohy. Hodnota je creative-lab-keychain-build.

  • Name
    name
    Type
    string
    Description

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

  • Name
    status
    Type
    string
    Description

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

  • Name
    progress
    Type
    integer
    Description

    Progress úlohy. Pokud úloha ještě nebyla zahájena, tato vlastnost bude 0. Jakmile úloha uspěje, hodnota bude 100.

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

    Časové razítko okamžiku zahájení úlohy, v milisekundách.

  • Name
    finished_at
    Type
    timestamp
    Description

    Časové razítko okamžiku dokončení úlohy, v milisekundách.

  • Name
    expires_at
    Type
    timestamp
    Description

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

  • Name
    preceding_tasks
    Type
    integer
    Description

    Počet předcházejících úloh. Má smysl pouze pokud je status 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. Vrací 0 u úloh se stavem FAILED (při selhání jsou kredity vráceny).

  • Name
    model_urls
    Type
    object
    Description

    Adresy URL ke stažení vygenerovaného artefaktu, indexované podle názvu artefaktu. Vždy obsahuje přesně jednu položku — formát požadovaný přes output.format v požadavku na build. Klíč odpovídá požadovanému formátu:

    • Name
      glb
      Type
      string
      Description

      Adresa URL ke stažení souboru GLB. Přítomna, pokud bylo output.format nastaveno na glb (výchozí hodnota).

    • Name
      obj
      Type
      string
      Description

      Adresa URL ke stažení zip balíčku obsahujícího model.obj, model.mtl a texture.png. Přítomna, pokud bylo output.format nastaveno na obj.

    • Name
      bundle_zip
      Type
      string
      Description

      Adresa URL ke stažení zip balíčku se všemi artefakty, které generátor vytváří. Přítomna, pokud bylo output.format nastaveno na zip.

Example Keychain Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}