Text na 3D API

Text na 3D API je funkce, která vám umožňuje integrovat schopnosti Meshy pro Text na 3D do vaší vlastní aplikace. V této sekci najdete všechny informace, které potřebujete k tomu, abyste s tímto API mohli začít pracovat.

Text na 3D používá dvoukrokový pracovní postup. Nejprve vytvořte úlohu preview (mode: "preview") pro vygenerování 3D sítě bez textury, abyste mohli posoudit tvar. Poté předejte ID dokončené úlohy preview do úlohy refine (mode: "refine"), aby se na síť aplikovala textura. Oba kroky sdílejí stejný koncový bod.

POST/openapi/v2/text-to-3d

Create a Text to 3D Preview Task

Tento koncový bod vytvoří úlohu Text na 3D preview, která vygeneruje z textového promptu 3D síť bez textur (pouze geometrii). Toto je první krok dvoukrokového pracovního postupu. Jakmile se preview úspěšně dokončí, použijte vrácené ID úlohy k vytvoření refine úlohy pro texturování. Úplné schéma odpovědi najdete v části Objekt úlohy Text na 3D.

Parametry

  • Name
    mode
    Type
    string
    Povinné
    Description

    Toto pole by mělo být při vytváření preview úlohy nastaveno na "preview".

  • Name
    prompt
    Type
    string
    Povinné
    Description

    Popište, o jaký typ objektu se u 3D modelu jedná. Maximálně 800 znaků.

  • Name
    model_type
    Type
    string
    výchozí standard
    Description

    Určuje typ generování 3D sítě.

    Dostupné hodnoty:

    • standard: Běžné generování 3D sítě s vysokou úrovní detailu.
    • smart-topology: Zvolte model Smart Topology pomocí ai_model (meshy-t2).
    • lowpoly (zastaralé): Generuje low-poly síť optimalizovanou pro čistší polygony. Doporučujeme místo toho použít smart-topology.

    Pokud je zvoleno smart-topology, parametry should_remesh a decimation_mode jsou ignorovány a přijímá se pouze topology: triangle.

    Pokud je zvoleno lowpoly, parametry ai_model, topology, target_polycount a should_remesh jsou ignorovány.

  • Name
    ai_model
    Type
    string
    výchozí latest
    Description

    ID modelu, který se má použít. Dostupné hodnoty závisí na model_type.

    Standardní generování (model_type: standard):

    • meshy-5, meshy-6, meshy-7, latest (Meshy 7)

    Generování Smart Topology (model_type: smart-topology):

    • meshy-t2 (výchozí): model Smart Topology — čistší topology, přirozeně oddělené části, výstup v trojúhelnících a počet ploch, který lze nastavit pomocí target_polycount.
  • Name
    ultra_mode
    Type
    boolean
    výchozí false
    Description

    Zapíná generování Ultra pro geometrii s vyšší věrností a jemnějším detailem povrchu. Generování trvá déle a přidává 5 kreditů.

    Podporováno pouze v případě, že ai_model je meshy-7 (nebo latest), a pouze v mode preview.

  • Name
    should_remesh
    Type
    boolean
    výchozí false (meshy-6, meshy-7), true (others)
    Description

    Určuje, zda povolit fázi remesh. Pro model s nejvyšší kvalitou doporučujeme nastavit should_remesh na false.

Platí pouze když should_remesh = true
  • Name
    topology
    Type
    string
    výchozí triangle
    Description

    Určuje topology vygenerovaného modelu.

    Dostupné hodnoty:

    • quad: Vygeneruje síť s převahou čtyřúhelníků (quad).
    • triangle: Vygeneruje decimovanou trojúhelníkovou síť.

    Výstup Smart Topology je pouze trojúhelníkový. Požadavek na quad společně s ai_model: meshy-t2 vrátí chybu.

  • Name
    decimation_mode
    Type
    integer
    Description

    Zapne adaptivní decimaci nastavením úrovně počtu polygonů. Je-li nastaveno, target_polycount je ignorováno.

    Dostupné hodnoty:

    • 1: Adaptivní — ultra počet polygonů.
    • 2: Adaptivní — vysoký počet polygonů.
    • 3: Adaptivní — střední počet polygonů.
    • 4: Adaptivní — nízký počet polygonů.
  • Name
    target_polycount
    Type
    integer
    Description

    Cílový počet polygonů (ploch) ve výstupu. Skutečný počet se může od cíle lišit v závislosti na geometrii.

    target_polycount se uplatní ve dvou nezávislých případech:

    • Remesh — s should_remesh: true u modelu standard. Síť je remeshována (decimována) na přibližně tento počet. Rozsah 100 až 300 000, výchozí hodnota 30 000. Pokud je nastaveno decimation_mode, má přednost a target_polycount je ignorováno.
    • Smart Topology — s model_type: smart-topology a ai_model: meshy-t2. Model je vygenerován přímo s tímto počtem ploch; remesh se nespouští a should_remesh není potřeba. Rozsah 100 až 15 000, výchozí hodnota 4 000.
  • Name
    symmetry_mode
    Type
    string
    ⚠ zastaralé
    výchozí auto
    Description

    Zastaralé. Tento parametr již neovlivňuje výstup.

    Pole symmetry_mode řídí chování symetrie během procesu generování modelu.

    Platné hodnoty jsou:

    • off: Vypne symetrii.
    • auto: Automaticky určí a použije symetrii na základě vstupní geometrie.
    • on: Vynutí symetrii během generování.
  • Name
    pose_mode
    Type
    string
    výchozí ""
    Description

    Určuje pose mode pro vygenerovaný model.

    Dostupné hodnoty:

    • a-pose: Vygeneruje model v pozici A.
    • t-pose: Vygeneruje model v pozici T.
    • "" (prázdný řetězec): Není použita žádná konkrétní póza.
  • Name
    is_a_t_pose
    Type
    boolean
    ⚠ zastaralé
    výchozí false
    Description

    Místo toho použijte pose_mode. Určuje, zda se má model vygenerovat v pozici A/T.

  • Name
    art_style
    Type
    string
    ⚠ zastaralé
    výchozí realistic
    Description

    Není podporováno Meshy-6. Požadavky s Meshy-6 budou art_style ignorovat a některé kombinace mohou způsobit chyby. Dostupné hodnoty: realistic, sculpture.

    enable_pbr by mělo být při použití stylu Sculpture nastaveno na false, protože styl Sculpture generuje vlastní sadu PBR map.

  • Name
    moderation
    Type
    boolean
    výchozí false
    Description

    Pokud je nastaveno na true, vstupní obsah bude automaticky zkontrolován na potenciálně škodlivý obsah. Pokud je škodlivý obsah zjištěn, úloha nebude pokračovat do fáze generování.

    Kontrolován bude text z prompt.

  • Name
    target_formats
    Type
    string[]
    Description

    Určuje, které formáty 3D souborů mají být zahrnuty do výstupu. Vygenerovány a vráceny budou pouze požadované formáty, což může zkrátit dobu dokončení úlohy. Pokud není zadáno, jsou zahrnuty všechny podporované formáty.

    Dostupné hodnoty: glb, obj, fbx, stl, usdz, 3mf

    Pokud není zadáno, jsou vygenerovány všechny formáty kromě 3mf. 3mf je zahrnuto pouze tehdy, je-li výslovně specifikováno.

  • Name
    alpha_thumbnail
    Type
    boolean
    výchozí false
    Description

    Pokud je nastaveno na true, úloha navíc vykreslí verzi náhledu s průhledným pozadím (RGBA) a vrátí ji jako alpha_thumbnail_url v odpovědi GET. Stávající pole thumbnail_url zůstává beze změny.

  • Name
    auto_size
    Type
    boolean
    výchozí false
    Description

    Pokud je nastaveno na true, služba použije AI vidění k automatickému odhadu reálné výšky objektu a odpovídajícím způsobem model změní velikost. Počátek bude standardně nastaven na bottom, pokud není origin_at výslovně nastaveno.

Platí pouze když auto_size = true
  • Name
    origin_at
    Type
    string
    výchozí bottom
    Description

    Pozice počátku, je-li povoleno auto_size.

    Dostupné hodnoty: bottom, center.

Návratové hodnoty

Vlastnost result v odpovědi obsahuje id úlohy nově vytvořené úlohy Text na 3D.

Chybové stavy

  • Name
    400 - Bad Request
    Description

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

    • Chybějící parametr: Chybí povinný parametr (např. prompt, mode).
    • Neplatný parametr: art_style neodpovídá žádné z povolených hodnot.
    • Prompt je příliš dlouhý: prompt překračuje limit počtu znaků.
  • 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
    429 - Too Many Requests
    Description

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

Request

POST
/openapi/v2/text-to-3d
# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with remesh and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
POST/openapi/v2/text-to-3d

Vytvoření úlohy Text na 3D Refine

Tento koncový bod vytvoří úlohu Text na 3D refine, která aplikuje texturu na dokončenou preview síť. Musíte poskytnout preview_task_id z úspěšné preview úlohy. Toto je druhý krok dvoukrokového pracovního postupu.

Parametry

  • Name
    mode
    Type
    string
    Povinné
    Description

    Toto pole by mělo být při vytváření refine úlohy nastaveno na "refine".

  • Name
    preview_task_id
    Type
    string
    Povinné
    Description

    Odpovídající ID preview úlohy.

    Stav dané preview úlohy musí být SUCCEEDED.

  • Name
    enable_pbr
    Type
    boolean
    výchozí false
    Description

    Vygeneruje PBR mapy (metallic, roughness, normal) navíc k základní barvě (base color). Emisní mapa (emission map) je zahrnuta také v případě, že ai_model je meshy-6, kromě případu texture_resolution: 8k (emisní mapa se v tomto případě nevytvoří). meshy-7 (a latest) emisní mapu nevytváří.

  • Name
    texture_resolution
    Type
    string
    výchozí 2k
    Description

    Rozlišení textury základní barvy (base color). Jedna z hodnot 2k (2048×2048), 4k (4096×4096) nebo 8k (8192×8192). Vyšší rozlišení zachycují více povrchových detailů. Platí pouze pro mode refine.

    4k a 8k vyžadují ai_model meshy-6, meshy-7 nebo latest. Při 8k se nevytváří emisní mapa.

  • Name
    hd_texture
    Type
    boolean
    ⚠ zastaralé
    výchozí false
    Description

    Místo tohoto parametru použijte texture_resolution — je ekvivalentní hodnotě texture_resolution: "4k". Pokud jsou nastaveny oba, má přednost texture_resolution.

  • Name
    texture_prompt
    Type
    string
    Description

    Poskytněte doplňující textový prompt, který navede proces texturování. Maximálně 800 znaků.

  • Name
    texture_image_url
    Type
    string
    Description

    Poskytněte 2D obrázek, který navede proces texturování. Aktuálně podporujeme formáty .jpg, .jpeg a .png.

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

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

    Texturování podle obrázku nemusí fungovat optimálně, pokud existují výrazné rozdíly v geometrii mezi původním assetem a nahraným obrázkem. K navedení procesu texturování lze použít pouze jeden z parametrů texture_image_url nebo texture_prompt. Pokud jsou poskytnuty oba parametry, model bude standardně texturován pomocí texture_prompt.

  • Name
    ai_model
    Type
    string
    výchozí zděděno z preview úlohy
    Description

    ID modelu, který se má použít pro refine. Dostupné hodnoty: meshy-5, meshy-6, meshy-7, latest (Meshy 7).

    Vynecháním tohoto parametru se zdědí model použitý v preview úloze, díky čemuž zůstávají preview i jeho refine na stejném modelu od začátku do konce. Explicitní hodnotou toto zdědění přepíšete.

    Explicitní hodnota latest se zde vyhodnotí přesně stejně jako u preview úlohy (aktuálně Meshy 7), takže preview s hodnotou latest a jeho refine s hodnotou latest vždy skončí na stejném texturovacím modelu.

  • Name
    moderation
    Type
    boolean
    výchozí false
    Description

    Pokud je nastaveno na true, vstupní obsah bude automaticky prověřen na potenciálně škodlivý obsah. Pokud je škodlivý obsah zjištěn, úloha nebude pokračovat ke generování.

    Prověřen bude jak text z texture_prompt, tak obrázek z texture_image_url.

  • Name
    remove_lighting
    Type
    boolean
    výchozí true
    Description

    Odstraní zvýraznění a stíny ze základní barevné textury (base color), čímž vznikne čistší výsledek, který lépe funguje s vlastním nastavením osvětlení.

    Uplatní se pouze v případě, že ai_model je meshy-6. U meshy-7 (a latest) je parametr přijat, ale ignorován.

  • Name
    target_formats
    Type
    string[]
    Description

    Určuje, které formáty 3D souborů se mají zahrnout do výstupu. Vygenerovány a vráceny budou pouze požadované formáty, což může zkrátit dobu dokončení úlohy. Pokud je vynecháno, jsou zahrnuty všechny podporované formáty.

    Dostupné hodnoty: glb, obj, fbx, stl, usdz, 3mf

    Pokud je vynecháno, vygenerují se všechny formáty kromě 3mf. 3mf je zahrnut pouze v případě, že je výslovně zadán.

  • Name
    alpha_thumbnail
    Type
    boolean
    výchozí false
    Description

    Pokud je nastaveno na true, úloha navíc vykreslí verzi náhledu s průhledným pozadím (RGBA) a vrátí ji v odpovědi GET jako alpha_thumbnail_url. Stávající pole thumbnail_url zůstává beze změny.

  • Name
    auto_size
    Type
    boolean
    výchozí false
    Description

    Pokud je nastaveno na true, služba použije AI vidění (AI vision) k automatickému odhadnutí reálné výšky objektu a odpovídajícímu přizpůsobení velikosti modelu. Počátek (origin) bude standardně nastaven na bottom, pokud není origin_at explicitně nastaven.

Platí pouze když auto_size = true
  • Name
    origin_at
    Type
    string
    výchozí bottom
    Description

    Pozice počátku (origin), pokud je povoleno auto_size.

    Dostupné hodnoty: bottom, center.

Návratová hodnota

Vlastnost result v odpovědi obsahuje id úlohy nově vytvořené úlohy Text na 3D.

Způsoby selhání

  • Name
    400 - Bad Request
    Description

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

    • Neplatné ID úlohy: preview_task_id je neplatné nebo neexistuje.
    • Úloha není připravena: Preview úloha ještě neskončila úspěchem.
    • Nesoulad modelů: AI model preview úlohy není kompatibilní s požadovaným refine modelem.
  • 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

    Preview úloha určená pomocí preview_task_id nebyla nalezena.

  • Name
    429 - Too Many Requests
    Description

    Překročili jste limit rychlosti.

Request

POST
/openapi/v2/text-to-3d
# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/v2/text-to-3d/:id

Načtení úlohy Text na 3D

Tento koncový bod umožňuje načíst úlohu Text na 3D na základě platného id úlohy. Podrobnosti o vlastnostech, které jsou součástí objektu úlohy Text na 3D, najdete v části Objekt úlohy Text na 3D.

Tento koncový bod funguje jak pro úlohy preview, tak pro úlohy refine.

Parametry

  • Name
    id
    Type
    path
    Description

    Unikátní identifikátor úlohy Text na 3D, kterou chcete načíst.

Návratová hodnota

Odpověď obsahuje objekt úlohy Text na 3D. Podrobnosti naleznete v části Objekt úlohy Text na 3D.

Příklady

ModeUkázkový model
PreviewPreview model
RefineRefined model

Request

GET
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}
DELETE/openapi/v2/text-to-3d/:id

Odstranění úlohy Text na 3D

Tento koncový bod trvale odstraní úlohu Text na 3D, včetně všech souvisejících modelů a dat. Tato akce je nevratná.

Parametry cesty

  • Name
    id
    Type
    path
    Description

    ID úlohy Text na 3D, kterou chcete odstranit.

Návratová hodnota

V případě úspěchu vrací 200 OK.

Request

DELETE
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.
GET/openapi/v2/text-to-3d

Seznam úloh Text na 3D

Tento koncový bod umožňuje získat seznam úloh Text na 3D.

Parametry

  • 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 50 položek.

  • Name
    sort_by
    Type
    string
    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ě.

Návratová hodnota

Vrací stránkovaný seznam objektů úlohy Text na 3D.

Request

GET
/openapi/v2/text-to-3d
curl https://api.meshy.ai/openapi/v2/text-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {

      "message": ""

    },

    "consumed_credits": 20
  }
]
GET/openapi/v2/text-to-3d/:id/stream

Streamování úlohy Text na 3D

Tento koncový bod streamuje aktualizace v reálném čase pro úlohu Text na 3D pomocí Server-Sent Events (SSE).

Parametry

  • Name
    id
    Type
    path
    Description

    Jedinečný identifikátor úlohy Text na 3D, kterou chcete streamovat.

Návratové hodnoty

Vrací proud objektů úlohy Text na 3D jako Server-Sent Events.

U úloh se stavem PENDING nebo IN_PROGRESS bude proud odpovědi obsahovat pouze potřebná pole progress a status.

Request

GET
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
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",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"texture_urls": [
  {
    "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
    "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
    "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
    "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
    "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
  }
],
"preceding_tasks": 0,
"task_error": {

  "message": ""

},

"consumed_credits": 20
}

The Text to 3D Task Object

Objekt Text to 3D Task je pracovní jednotka, kterou Meshy sleduje za účelem generování 3D modelu z textového vstupu. Text na 3D API má dvě fáze, preview a refine. Fáze preview slouží ke generování 3D modelu obsahujícího pouze síť, zatímco fáze refine slouží ke generování texturovaného 3D modelu na základě výsledku fáze preview.

Objekt má následující vlastnosti:

Properties

  • Name
    id
    Type
    string
    Description

    Unikátní identifikátor úlohy. Přestože 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 Text na 3D. Možné hodnoty jsou text-to-3d-preview pro úlohy fáze preview a text-to-3d-refine pro úlohy fáze refine.

  • Name
    model_urls
    Type
    object
    Description

    Stažitelná URL adresa na texturovaný soubor 3D modelu vygenerovaný Meshy. Vlastnost pro daný formát bude vynechána, pokud daný formát nebyl vygenerován, namísto vrácení prázdného řetězce.

    • Name
      glb
      Type
      string
      Description

      Stažitelná URL adresa na soubor GLB.

    • Name
      fbx
      Type
      string
      Description

      Stažitelná URL adresa na soubor FBX.

    • Name
      usdz
      Type
      string
      Description

      Stažitelná URL adresa na soubor USDZ.

    • Name
      obj
      Type
      string
      Description

      Stažitelná URL adresa na soubor OBJ.

    • Name
      mtl
      Type
      string
      Description

      Stažitelná URL adresa na soubor MTL.

    • Name
      stl
      Type
      string
      Description

      Stažitelná URL adresa na soubor STL.

    • Name
      3mf
      Type
      string
      Description

      Stažitelná URL adresa na soubor 3MF. Přítomno pouze v případě, že formát 3mf byl vyžádán prostřednictvím target_formats.

  • Name
    prompt
    Type
    string
    Description

    Toto je nezměněný prompt, který byl použit k vytvoření úlohy.

  • Name
    negative_prompt
    Type
    string
    ⚠ zastaralé
    Description

    Udržováno kvůli zpětné kompatibilitě. Toto pole nemá žádný funkční vliv na generované modely.

  • Name
    art_style
    Type
    string
    ⚠ zastaralé
    Description

    Nezměněný art_style, který byl použit k vytvoření úlohy preview. Není podporováno modelem Meshy-6.

  • Name
    texture_richness
    Type
    string
    ⚠ zastaralé
    Description

    Udržováno kvůli zpětné kompatibilitě. Toto pole nemá žádný funkční vliv na generované modely.

  • Name
    texture_prompt
    Type
    string
    Description

    Dodatečný textový prompt poskytnutý pro řízení procesu texturování během fáze refine.

  • Name
    ultra_mode
    Type
    boolean
    Description

    Opakuje hodnotu ultra_mode, se kterou byla vytvořena úloha preview. Přítomno pouze u úloh preview modelu meshy-7 (nebo latest), které explicitně nastavily ultra_mode; jinak je vynecháno.

  • Name
    texture_image_url
    Type
    string
    Description

    Stažitelná URL adresa na obrázek textury, který byl použit k řízení procesu texturování.

  • Name
    thumbnail_url
    Type
    string
    Description

    Stažitelná URL adresa na miniaturu souboru modelu.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    Stažitelná URL adresa na verzi thumbnail_url s průhledným pozadím (RGBA). Přítomno pouze v případě, že úloha byla vytvořena s alpha_thumbnail: true a průhledný náhled byl úspěšně vykreslen; jinak je toto pole vynecháno.

  • Name
    video_url
    Type
    string
    ⚠ zastaralé
    Description

    Stažitelná URL adresa na náhledové video. Bude odstraněno v budoucí verzi.

  • Name
    progress
    Type
    integer
    Description

    Průběh úlohy (progress). Pokud úloha ještě nebyla spuštěna, tato vlastnost bude 0. Jakmile úloha uspěje, hodnota se změní na 100.

  • Name
    started_at
    Type
    timestamp
    Description

    Časové razítko okamžiku, kdy byla úloha spuštěna, v milisekundách. Pokud úloha ještě nebyla spuštěna, tato vlastnost bude 0.

    Č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 reprezentován jako 1693569600000. To platí pro všechna časová razítka v Meshy API.

  • Name
    created_at
    Type
    timestamp
    Description

    Časové razítko okamžiku, kdy byla úloha vytvořena, v milisekundách.

  • Name
    finished_at
    Type
    timestamp
    Description

    Časové razítko okamžiku, kdy byla úloha dokončena, v milisekundách. Pokud úloha ještě není dokončena, tato vlastnost bude 0.

  • Name
    status
    Type
    string
    Description

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

  • Name
    texture_urls
    Type
    array
    Description

    Pole objektů URL textur vygenerovaných úlohou. Obvykle obsahuje pouze jeden objekt URL textury. Každá URL textury má následující vlastnosti:

    • Name
      base_color
      Type
      string
      Description

      Stažitelná URL adresa na obrázek mapy základní barvy.

    • Name
      metallic
      Type
      string
      Description

      Stažitelná URL adresa na obrázek metalické mapy.

      Pokud je úloha vytvořena s enable_pbr: false, tato vlastnost bude vynechána.

    • Name
      normal
      Type
      string
      Description

      Stažitelná URL adresa na obrázek normálové mapy.

      Pokud je úloha vytvořena s enable_pbr: false, tato vlastnost bude vynechána.

    • Name
      roughness
      Type
      string
      Description

      Stažitelná URL adresa na obrázek mapy drsnosti.

      Pokud je úloha vytvořena s enable_pbr: false, tato vlastnost bude vynechána.

    • Name
      emission
      Type
      string
      Description

      Stažitelná URL adresa na obrázek emisní mapy.

      Pokud je úloha vytvořena s enable_pbr: false, nebo pokud je ai_model roven meshy-5, tato vlastnost bude vynechána.

  • Name
    preceding_tasks
    Type
    integer
    Description

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

    Hodnota tohoto pole má smysl pouze v případě, že stav úlohy je PENDING.

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

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

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}