Text na 3D API

Text na 3D API je funkce, která vám umožňuje integrovat schopnosti Meshy Text na 3D do vaší vlastní aplikace. V této části naleznete veškeré informace potřebné k zahájení práce s tímto API.

Text na 3D používá dvoustupňový pracovní postup. Nejprve vytvoříte úlohu náhledu (mode: "preview") pro generování 3D sítě bez textury, takže můžete ohodnotit tvar. Poté předáte ID úlohy dokončeného náhledu do úlohy detailování (mode: "refine") pro aplikaci textury na síť. Oba kroky sdílejí stejný koncový bod.

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

Vytvoření úlohy náhledu Text na 3D

Tento koncový bod vytváří úlohu náhledu Text na 3D, která generuje neotexturovanou 3D síť (pouze geometrii) ze zadaného textového promptu. Jedná se o první krok dvoustupňového pracovního postupu. Jakmile náhled uspěje, použijte vrácené ID úlohy k vytvoření úlohy detailování pro texturování. Pro plnou odpověď schématu se podívejte na Objekt úlohy Text na 3D.

Parametry

  • Name
    mode
    Type
    string
    Povinné
    Description

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

  • Name
    prompt
    Type
    string
    Povinné
    Description

    Popište, o jaký druh objektu se jedná. Maximálně 600 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 vysokým detailem.
    • smart-topology: Vyberte model Smart Topology s ai_model (meshy-t2).
    • lowpoly (zastaralé): Generuje low-poly síť optimalizovanou pro čistější polygony. Doporučujeme používat místo toho smart-topology.

    Když je vybrán smart-topology, should_remesh a decimation_mode jsou ignorovány a přijímána je pouze topology: triangle.

    Když je vybrán lowpoly, ai_model, topology, target_polycount a should_remesh jsou ignorovány.

  • Name
    ai_model
    Type
    string
    výchozí latest
    Description

    ID modelu k použití. 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ší topologie, nativně oddělené části, výstup trojúhelníků a počet obličejů, který lze nastavit pomocí target_polycount.
  • Name
    ultra_mode
    Type
    boolean
    výchozí false
    Description

    Povolí Ultra generování pro vyšší věrnost geomerie s jemnějšími povrchovými detaily. Generování trvá déle a přidává 5 kreditů.

    Podporováno pouze, když je ai_model meshy-7 (nebo latest) a pouze v preview mode.

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

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

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

    Určuje topologii generovaného modelu.

    Dostupné hodnoty:

    • quad: Generuje síť s dominancí koster.
    • triangle: Generuje zdecimovanou síť trojúhelníků.

    Výstup Smart Topology je pouze trojúhelníkový. Dotaz na quad spolu s ai_model: meshy-t2 vrací chybu.

  • Name
    decimation_mode
    Type
    integer
    Description

    Povolit adaptivní decimaci nastavením úrovně polycount. Pokud je nastavena, target_polycount je ignorován.

    Dostupné hodnoty:

    • 1: Adaptivní — ultra polycount.
    • 2: Adaptivní — vysoký polycount.
    • 3: Adaptivní — střední polycount.
    • 4: Adaptivní — nízký polycount.
  • Name
    target_polycount
    Type
    integer
    Description

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

    target_polycount účinkuje ve dvou nezávislých případech:

    • Remesh — s should_remesh: true na standardním modelu. Síť je remeshed (decimovaná) přibližně na tento počet. Rozsah 100 až 300 000, výchozí 30 000. Pokud je nastaveno decimation_mode, má přednost a target_polycount je ignorován.
    • Smart Topology — s model_type: smart-topology a ai_model: meshy-t2. Model je generován přímo na tento počet obličejů; žádné remesh není spuštěno a should_remesh není potřebný. Rozsah 100 až 15 000, výchozí 4 000.
  • Name
    symmetry_mode
    Type
    string
    ⚠ zastaralé
    výchozí auto
    Description

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

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

    Platné hodnoty jsou:

    • off: Zakáže symetrii
    • auto: Automaticky určuje a aplikuje symetrii na základě vstupní geometrie.
    • on: Vynucuje symetrii při generování.
  • Name
    pose_mode
    Type
    string
    výchozí ""
    Description

    Určuje pozice mode pro generovaný model.

    Dostupné hodnoty:

    • a-pose: Vytvoří model v A-pozici.
    • t-pose: Vytvoří model v T-pozici.
    • "" (prázdný řetězec): Neaplikuje se žádná konkrétní pozice.
  • Name
    is_a_t_pose
    Type
    boolean
    ⚠ zastaralé
    výchozí false
    Description

    Použijte pose_mode místo toho. Zda generovat model v A/T pozici.

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

    Nepodporováno Meshy-6. Dotazy používající Meshy-6 budou ignorovat art_style a některé kombinace mohou způsobit chyby. Dostupné hodnoty: realistic, sculpture.

    enable_pbr by mělo být nastaveno na false, když používáte styl okamžité plastiky, jako sochařský styl generuje svou vlastní sadu PBR map.

  • Name
    moderation
    Type
    boolean
    výchozí false
    Description

    Při nastavení na true je vstupní obsah automaticky kontrolován na potenciálně škodlivý obsah. Pokud je zjištěn škodlivý obsah, úloha nepokračuje k generování.

    Text z prompt bude zkontrolován.

  • Name
    target_formats
    Type
    string[]
    Description

    Určuje, které formáty 3D souborů zahrnout do výstupu. Budou generovány a vráceny pouze požadované formáty, což může snížit dobu dokončení úlohy. Při vynechání jsou zahrnuty všechny podporované formáty.

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

    Při vynechání jsou generovány všechny formáty kromě 3mf. 3mf je zahrnut pouze, když je explicitně zadán.

  • Name
    alpha_thumbnail
    Type
    boolean
    výchozí false
    Description

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

  • Name
    auto_size
    Type
    boolean
    výchozí false
    Description

    Když je nastaveno na true, služba používá AI vision ke automatickému odhadu skutečné výšky objektu a úpravy velikosti modelu. Počátek bude ve výchozím nastavení bottom, pokud není explicitně nastaven origin_at.

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

    Pozice počátku při zapnuté funkci auto_size.

    Dostupné hodnoty: bottom, center.

Návraty

result vlastnost 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ý. Běžné příčiny:

    • Chybějící parametr: Chybí potřebný parametr (např. prompt, mode).
    • Neplatný parametr: art_style není jednou z povolených hodnot.
    • Příliš dlouhý prompt: prompt přesahuje limit znaků.
  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

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

  • Name
    429 - Too Many Requests
    Description

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

Požadavek

POST
/openapi/v2/text-to-3d
# Jednoduchý náhled pouze s požadovanými parametry
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"
}'

# Náhled s remesh a A-pozicí
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"]
}'

Odpověď

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

Vytvoření úlohy detailování Text na 3D

Tento koncový bod vytváří úlohu detailování Text na 3D, která aplikuje texturu na dokončenou náhledovou síť. Musíte poskytnout preview_task_id z úspěšné úlohy náhledu. Jedná se o druhý krok dvoustupňového pracovního postupu.

Parametry

  • Name
    mode
    Type
    string
    Povinné
    Description

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

  • Name
    preview_task_id
    Type
    string
    Povinné
    Description

    Odpovídající ID úlohy náhledu.

    Status zadané úlohy náhledu musí být SUCCEEDED.

  • Name
    enable_pbr
    Type
    boolean
    výchozí false
    Description

    Generovat PBR mapy (metalické, drsnosti, normálové) navíc k základní barvě. Emisní mapa je zahrnuta také při ai_model je meshy-6, kromě texture_resolution: 8k (žádná emisní mapa není vytvořena).meshy-7 (a latest) nevytváří emisní mapu.

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

    Rozlišení textury základní barvy. Jde o jedno z 2k (2048×2048), 4k (4096×4096) nebo 8k (8192×8192). Vyšší rozlišení zachytí více detailů povrchu. Platí pouze pro refine mode.

    4k a 8k vyžadují ai_model meshy-6, meshy-7 nebo latest. Při 8k není vytvářena žádná emisní mapa.

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

    Použijte místo toho texture_resolution — ekvivalentní texture_resolution: "4k". Pokud jsou nastaveny obě, texture_resolution má přednost.

  • Name
    texture_prompt
    Type
    string
    Description

    Poskytněte další textový prompt pro vedení procesu texturování. Maximálně 600 znaků.

  • Name
    texture_image_url
    Type
    string
    Description

    Poskytněte 2D obraz pro vedení procesu texturování. Momentálně podporujeme formáty .jpg, .jpeg a .png.

    Existují dva způsoby, jak obraz poskytnout:

    • Veřejně přístupné URL: URL, které je přístupné z veřejného internetu
    • Data URI: Base64-kódovaná data URI obrazu. Příklad Data URI: data:image/jpeg;base64,<váš base64-kódovaný obraz>

    Texturování obrazu nemusí fungovat optimálně, pokud existují podstatné rozdíly v geometrii mezi původním assetem a nahraným obrazem. Pro vedení procesu texturování mohou být použity pouze jedno texture_image_url nebo texture_prompt. Pokud jsou poskytnuty oba parametry, pak texture_prompt bude použit pro výchozí model texturování.

  • Name
    ai_model
    Type
    string
    výchozí latest
    Description

    ID modelu k použití pro detailování. Dostupné hodnoty: meshy-5, meshy-6, meshy-7, latest (Meshy 7).

    latest se zde řeší stejně jako u úlohy náhledu (aktuálně Meshy 7), takže latest náhled a jeho latest detailování vždy skončí na stejném textuře modelu.

  • Name
    moderation
    Type
    boolean
    výchozí false
    Description

    Při nastavení na true je vstupní obsah automaticky zkontrolován na potenciálně škodlivý obsah. Pokud je zjištěn škodlivý obsah, úloha nebude pokračovat v generování.

    Kontrolován bude jak text z texture_prompt, tak i obraz z texture_image_url.

  • Name
    remove_lighting
    Type
    boolean
    výchozí true
    Description

    Odstraní odlesky a stíny z textury základní barvy, což vytvoří čistší výsledek, který lépe funguje v rámci vlastních nastavení osvětlení.

    Účinkuje pouze, když je ai_model meshy-6. Na meshy-7 (a latest) je parametr přijat, ale ignorován.

  • Name
    target_formats
    Type
    string[]
    Description

    Určuje, které formáty 3D souborů zahrnout do výstupu. Budou generovány a vráceny pouze požadované formáty, což může snížit dobu dokončení úlohy. Pokud jsou vynechány, jsou zahrnuty všechny podporované formáty.

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

    Pokud jsou vynechány, jsou generovány všechny formáty kromě 3mf. 3mf je zahrnut pouze, když je explicitně zadán.

  • Name
    alpha_thumbnail
    Type
    boolean
    výchozí false
    Description

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

  • Name
    auto_size
    Type
    boolean
    výchozí false
    Description

    Pokud je nastavena na true, služba používá AI vision ke automatickému odhadu skutečné výšky objektu a úpravě velikosti modelu. Počátek bude ve výchozím nastavení bottom, pokud není explicitně nastaven origin_at.

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

    Pozice počátku při zapnuté funkci auto_size.

    Dostupné hodnoty: bottom, center.

Návraty

result vlastnost 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ý. Běžné příčiny:

    • Neplatné ID úlohy: preview_task_id je neplatný nebo neexistuje.
    • Úloha není připravena: Úloha náhledu zatím nebyla úspěšná.
    • Neladící modely: AI model úlohy náhledu není kompatibilní s požadovaným modelem detailování.
  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

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

  • Name
    404 - Not Found
    Description

    Úloha náhledu specifikovaná preview_task_id nebyla nalezena.

  • Name
    429 - Too Many Requests
    Description

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

Požadavek

POST
/openapi/v2/text-to-3d
# Základní úloha detailování
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
}'

# Detailování s auto-size a GLB formátem
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
}'

Odpověď

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

Získání úlohy Text na 3D

Tento koncový bod vám umožňuje získat úlohu Text na 3D pomocí platného id úloh. Podívejte se na Objekt úlohy Text na 3D, abyste zjistili, jaké vlastnosti jsou zahrnuty v objektu úlohy Text na 3D.

Tento koncový bod funguje jak pro úlohy náhledu, tak pro úlohy detailování.

Parametry

  • Name
    id
    Type
    path
    Description

    Unikátní identifikátor úlohy Text na 3D ke získání.

Návraty

Odpověď obsahuje objekt úlohy Text na 3D. Podívejte se na část Objekt úlohy Text na 3D pro podrobnosti.

Příklady

ModeUkázkový model
NáhledPreview model
DetailováníRefined model

Požadavek

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

Odpověď

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

Smazání úlohy Text na 3D

Tento koncový bod trvale smaže ú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 ke smazání.

Návraty

Vrací 200 OK při úspěchu.

Požadavek

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

Odpověď

// Vrací 200 Ok při úspěchu.
GET/openapi/v2/text-to-3d

Vypiš úlohy Text na 3D

Tento koncový bod vám 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ánek. Maximálně povoleno je 50 položek.

  • Name
    sort_by
    Type
    string
    Description

    Pole pro třídění.

    Dostupné hodnoty:

    • +created_at: Třídění podle času vytvoření vzestupně.
    • -created_at: Třídění podle času vytvoření sestupně.

Návraty

Vrací stránkovaný seznam Objektů úloh Text na 3D.

Požadavek

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

Odpověď

[
  {
    "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

    Unikátní identifikátor pro úlohu Text na 3D ke streamování.

Návraty

Vrací stream Objektů úloh Text na 3D jako Server-Sent Events.

Pro PENDING nebo IN_PROGRESS úlohy bude stream odpovědi obsahovat pouze potřebná pole progress a status.

Požadavek

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

Stream odpovědi

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

Objekt úlohy Text na 3D

Objekt úlohy Text na 3D je pracovní jednotka, kterou Meshy sleduje pro generování 3D modelu z textového vstupu. Existují dvě fáze Text na 3D API, preview a refine. Fáze náhledu slouží k generování sítě pouze 3D modelu a fáze detailování slouží k generování texturovaného 3D modelu na základě výsledku fáze náhledu.

Objekt má následující vlastnosti:

Vlastnosti

  • Name
    id
    Type
    string
    Description

    Unikátní identifikátor pro úlohu. Používáme tříděné UUID pro ID úloh jako implementační detail, ale neměli byste si vytvářet žádné předpoklady ohledně 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 náhledu a text-to-3d-refine pro úlohy fáze detailování.

  • Name
    model_urls
    Type
    object
    Description

    Stahovatelná URL na texturovaný 3D modelový soubor generovaný Meshy. Vlastnost pro formát bude vynechána, pokud není formát generován, namísto vrácení prázdného řetězce.

    • Name
      glb
      Type
      string
      Description

      Stahovatelná URL na GLB soubor.

    • Name
      fbx
      Type
      string
      Description

      Stahovatelná URL na FBX soubor.

    • Name
      usdz
      Type
      string
      Description

      Stahovatelná URL na USDZ soubor.

    • Name
      obj
      Type
      string
      Description

      Stahovatelná URL na OBJ soubor.

    • Name
      mtl
      Type
      string
      Description

      Stahovatelná URL na MTL soubor.

    • Name
      stl
      Type
      string
      Description

      Stahovatelná URL na STL soubor.

    • Name
      3mf
      Type
      string
      Description

      Stahovatelná URL na 3MF soubor. Přítomná pouze, pokud byl 3mf požádán přes 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ženo kvůli zajištění zpětné kompatibility. Toto pole nemá žádný funkční dopad na generované modely.

  • Name
    art_style
    Type
    string
    ⚠ zastaralé
    Description

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

  • Name
    texture_richness
    Type
    string
    ⚠ zastaralé
    Description

    Udrženo kvůli zajištění zpětné kompatibility. Toto pole nemá žádný funkční dopad na generované modely.

  • Name
    texture_prompt
    Type
    string
    Description

    Další textový prompt poskytnutý k vedení procesu texturování během fáze detailování.

  • Name
    ultra_mode
    Type
    boolean
    Description

    Opakuje ultra_mode hodnotu, s kterou byla úloha náhledu vytvořena. Přítomná pouze pro úlohy náhledu meshy-7 (nebo latest), které explicitně nastavují ultra_mode; jinak vynecháno.

  • Name
    texture_image_url
    Type
    string
    Description

    Stahovatelná URL na texturu obrazu, která byla použita k vedení procesu texturování.

  • Name
    thumbnail_url
    Type
    string
    Description

    Stahovatelná URL na miniaturu obrazu modelového souboru.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    Stahovatelná URL na verzi s průhledným pozadím (RGBA) thumbnail_url. Přítomná pouze, když byla úloha vytvořena s alpha_thumbnail: true a průhledný náhled byl úspěšně renderován; v opačném případě je toto pole vynecháno.

  • Name
    video_url
    Type
    string
    ⚠ zastaralé
    Description

    Stahovatelná URL na náhledové video. Bude odstraněno v budoucím vydání.

  • Name
    progress
    Type
    integer
    Description

    Pokrok úlohy. Pokud úloha zatím nebyla spuštěna, tato vlastnost bude 0. Jakmile úloha uspěla, toto bude 100.

  • Name
    started_at
    Type
    timestamp
    Description

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

    Časové razítko představuje počet milisekund, které uplynuly od 1. ledna 1970 UTC, následující standard RFC 3339. Například, pátek, 1. září 2023 12:00:00 PM GMT je reprezentován jako 1693569600000. Toto platí pro všechny časové razítka v Meshy API.

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

    Časové razítko, kdy úloha byla dokončena, v milisekundách. Pokud úloha není zatím dokončena, tato vlastnost bude 0.

  • Name
    status
    Type
    string
    Description

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

  • Name
    texture_urls
    Type
    array
    Description

    Pole objektů URL textur, které byly vytvořeny úlohou. Obvykle obsahuje jedno objekt URL textury. Každý URL textury má tyto vlastnosti:

    • Name
      base_color
      Type
      string
      Description

      Stahovatelná URL na obraz základní barevné mapy.

    • Name
      metallic
      Type
      string
      Description

      Stahovatelná URL na obraz kovové mapy.

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

    • Name
      normal
      Type
      string
      Description

      Stahovatelná URL na obraz normálové mapy.

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

    • Name
      roughness
      Type
      string
      Description

      Stahovatelná URL na obraz mapy drsnosti.

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

    • Name
      emission
      Type
      string
      Description

      Stahovatelná URL na obraz emisní mapy.

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

  • Name
    preceding_tasks
    Type
    integer
    Description

    Počet předchozích úloh.

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

  • Name
    task_error
    Type
    object
    Description

    Podrobnosti o chybě pro neúspěšné úlohy. Viz Chyby pro plný odkaz na objekt task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Počet kreditů spotřebovaných touto úlohou. Přítomna, pokud je stav úlohy PENDING, IN_PROGRESS nebo SUCCEEDED. Vrací 0 pro FAILED úlohy (kredity jsou vratné při neúspěchu).

Příklad objektu úlohy Text na 3D

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