Obrázek na 3D API

Obrázek na 3D API je funkce, která vám umožňuje integrovat možnosti Meshy pro Obrázek 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.

POST/openapi/v1/image-to-3d

Create an Image to 3D Task

Tento koncový bod umožňuje vytvořit novou úlohu Obrázek na 3D. Podrobnosti o vlastnostech obsažených v objektu úlohy Obrázek na 3D naleznete v části Objekt úlohy Obrázek na 3D.

Úloha běží na pozadí. Jak dlouho to obvykle trvá, se dozvíte v části Doby zpracování.

Parametry

Povinný je pouze jeden z parametrů input_task_id nebo image_url. Pokud jsou zadány oba, má přednost input_task_id.

Name
input_task_id
Type
string
Povinné
Description
ID dokončené úlohy generování obrázku, jejíž výstup se má použít jako vstupní obrázek. Tato úloha musí být jedna z následujících úloh: Text na obrázek nebo Obrázek na obrázek. Navíc musela proběhnout přes API, mít stav SUCCEEDED a vytvořit přesně jeden obrázek.

Name
image_url
Type
string
Povinné
Description
Poskytněte obrázek, který Meshy použije při vytváření modelu. Aktuálně podporujeme formáty .jpg, .jpeg, .png a .webp.
Maximální velikost souboru: 20 MB.
Obrázek lze zadat dvěma způsoby:
- Veřejně dostupná URL adresa: URL adresa, která je přístupná z veřejného internetu.
- Data URI: Obrázek zakódovaný ve formátu base64 jako data URI. Příklad data URI: data:image/jpeg;base64,<vaše base64 zakódovaná data obrázku>.

Name
model_type
Type
string
výchozí standard
Description
Zadejte typ generování 3D sítě.
Dostupné hodnoty:
- standard: Běžné generování 3D sítě ve vysoké kvalitě.
- smart-topology: Zvolte model Smart Topology pomocí ai_model (meshy-t2).
- lowpoly (zastaralé, bude vyřazeno 30. října 2026): Generuje low-poly síť optimalizovanou pro čistší polygony. Místo toho doporučujeme Meshy T2: smart-topology s meshy-t2.
Pokud je zvoleno smart-topology, parametry should_remesh, save_pre_remeshed_model a decimation_mode jsou ignorovány a je akceptováno pouze topology: triangle.
lowpoly bude vyřazeno 30. října 2026. Po tomto datu budou požadavky s model_type: "lowpoly" vracet chybu. Doporučujeme přejít na Meshy T2 (model_type: "smart-topology" s ai_model: "meshy-t2"). Pokud je zvoleno lowpoly, parametry ai_model, topology, target_polycount, should_remesh a save_pre_remeshed_model 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-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (zastaralé): místo toho použijte meshy-7.1.
Generování Smart Topology (model_type: smart-topology):
- meshy-t2 (výchozí): model Smart Topology — čistší topology, přirozeně oddělené části, trojúhelníkový výstup a počet stěn, který lze nastavit pomocí target_polycount.
Name
geometry_resolution
Type
string
výchozí standard
Description
Průchod generování geometrie. 2k spouští Ultra průchod v rozlišení 2048³; 4k jej spouští v rozlišení 4096³ pro nejjemnější detail povrchu.
Dostupné hodnoty: standard, 2k, 4k
Vyžaduje meshy-7.1 nebo latest.
Name
ultra_mode
Type
boolean
⚠ zastaralé
výchozí false
Description
Místo toho použijte geometry_resolution. ultra_mode: true odpovídá hodnotě geometry_resolution: "2k".
Name
should_texture
Type
boolean
výchozí true
Description
Určuje, zda se mají generovat textury. Nastavením na false se přeskočí fáze texturování a vznikne síť bez textur.

Platí pouze když should_texture = true

Name
enable_pbr
Type
boolean
výchozí false
Description
Vygeneruje PBR mapy (metalíza, drsnost, normálová mapa) navíc k základní barvě. Pokud je ai_model nastaveno na meshy-6, je zahrnuta i emisní mapa, s výjimkou texture_resolution: 8k. Modely meshy-6-lite, meshy-7.1, meshy-t2 a latest emisní mapu negenerují.
Name
texture_resolution
Type
string
výchozí 2k
Description
Rozlišení textury základní barvy. Jedna z hodnot 2k (2048×2048), 4k (4096×4096) nebo 8k (8192×8192). Vyšší rozlišení zachycují více detailů povrchu.
4k a 8k nejsou dostupné s ai_model meshy-6-lite. Při 8k není generována žádná emisní mapa.
Name
hd_texture
Type
boolean
⚠ zastaralé
výchozí false
Description
Místo toho použijte texture_resolution — odpovídá hodnotě texture_resolution: "4k". Pokud jsou nastaveny oba parametry, má přednost texture_resolution.
Name
texture_prompt
Type
string
Description
Zadejte textový prompt, kterým se bude řídit proces texturování. Maximálně 800 znaků.
Name
texture_image_url
Type
string
Description
Poskytněte 2D obrázek, kterým se bude řídit proces texturování. Aktuálně podporujeme formáty .jpg, .jpeg, .png a .webp.
Maximální velikost souboru: 20 MB.
Obrázek lze zadat dvěma způsoby:
- Veřejně dostupná URL adresa: URL adresa, která je přístupná z veřejného internetu
- Data URI: Obrázek zakódovaný ve formátu base64 jako data URI. Příklad data URI: data:image/jpeg;base64,<vaše base64 zakódovaná data obrázku>
Texturování pomocí obrázku nemusí fungovat optimálně, pokud existují výrazné rozdíly v geometrii mezi původním assetem a nahraným obrázkem. Proces texturování lze řídit pouze jedním z parametrů texture_image_url nebo texture_prompt. Pokud jsou zadány oba parametry, bude model ve výchozím nastavení texturován pomocí texture_prompt. Texturování pomocí textu nebo obrázku stojí 10 kreditů za úlohu.

Name
should_remesh
Type
boolean
výchozí false (Meshy 6 and Meshy 7 models), true (others)
Description
Řídí, zda se má povolit fáze remeshe. 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
Zadejte topology generovaného modelu.
Dostupné hodnoty:
- quad: Vygeneruje síť s převažujícími čtyřúhelníky.
- triangle: Vygeneruje decimovanou trojúhelníkovou síť.
Výstup Smart Topology je pouze trojúhelníkový. Požadavek quad společně s ai_model: meshy-t2 vrátí chybu.
Name
decimation_mode
Type
integer
Description
Povolí adaptivní decimaci nastavením úrovně počtu polygonů. Pokud je 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
save_pre_remeshed_model
Type
boolean
výchozí false
Description
Pokud je nastaveno na true, Meshy navíc uloží dodatečný soubor GLB před dokončením fáze remeshe.

Name
target_polycount
Type
integer
Description
Cílový počet polygonů (stěn) 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 stěn; neprobíhá žádný remesh a should_remesh není vyžadováno. 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 aplikuje symetrii na základě vstupní geometrie.
- on: Vynutí symetrii během generování.
Name
pose_mode
Type
string
výchozí ""
Description
Zadejte mode pózy pro generovaný model.
Dostupné hodnoty:
- a-pose: Vygeneruje model v póze A.
- t-pose: Vygeneruje model v póze T.
- "" (prázdný řetězec): Není aplikována žádná konkrétní póza.
Name
is_a_t_pose
Type
boolean
⚠ zastaralé
výchozí false
Description
Místo toho použijte pose_mode. Zda vygenerovat model v póze A/T.
Name
surface_mode
Type
string
⚠ zastaralé
Description
Již neovlivňuje výstup. Vybíral mode generování modelu, který byl od té doby vyřazen; místo toho použijte ai_model.
Přijímané hodnoty jsou organic a hard; jakákoli jiná hodnota vrátí 400.
Name
image_enhancement
Type
boolean
výchozí true
Description
Optimalizuje vstupní obrázek pro lepší výsledky. Nastavením na false se zachová přesný vzhled vstupního obrázku bez jakéhokoli stylového zpracování.
Podporováno pouze v případě, že ai_model je meshy-6, meshy-7.1 nebo latest. Nastavení s meshy-6-lite nebo s model_type: smart-topology vrátí chybu.
Name
remove_lighting
Type
boolean
výchozí true
Description
Odstraní zvýraznění a stíny ze základní barevné textury, čímž vznikne čistší výsledek, který lépe funguje v nestandardních nastaveních osvětlení.
Má efekt pouze v případě, že ai_model je meshy-6. meshy-7.1 a latest tento parametr přijímají, ale ignorují jej. Nastavení s meshy-6-lite nebo s model_type: smart-topology vrátí chybu.
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 zjištěn škodlivý obsah, úloha nebude pokračovat do fáze generování.
Prověřen bude obsah vstupů image_url, texture_image_url a texture_prompt.
Name
target_formats
Type
string[]
Description
Určuje, které formáty 3D souborů mají být zahrnuty ve 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ě uvedeno.
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 upraví velikost modelu. Počátek bude ve výchozím nastavení bottom, pokud není výslovně nastaveno origin_at.
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 se nemění.
Name
multi_view_thumbnails
Type
boolean
výchozí false
Description
Pokud je nastaveno na true, úloha navíc vykreslí čtyři náhledy v hlavních pohledech (zepředu, zprava, zezadu, zleva) a vrátí je v poli thumbnail_urls v odpovědi GET. Stávající pole thumbnail_url se nemění a nadále odkazuje na pohled zepředu, takže stávající klienty to neovlivní.
Zvyšuje latenci úlohy přibližně o 3 sekundy.

Platí pouze když auto_size = true

Name
origin_at
Type
string
výchozí bottom
Description
Pozice počátku, pokud je povoleno auto_size.
Dostupné hodnoty: bottom, center.

Návratová hodnota

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

Režimy selhání

Name
400 - Bad Request
Description
Požadavek byl nepřijatelný. Časté příčiny:
- Chybějící parametr: Musí být zadáno buď image_url, nebo input_task_id.
- Neplatná vstupní úloha: input_task_id musí odkazovat na úlohu Text na obrázek nebo Obrázek na obrázek se stavem SUCCEEDED, která vytvoří přesně jeden obrázek.
- Neplatný formát obrázku: Zadaná hodnota image_url není v podporovaném formátu (.jpg, .jpeg, .png, .webp).
- Nedostupná URL adresa: image_url se nepodařilo stáhnout (404 nebo timeout).
- Obrázek je příliš velký: Obrázek image_url nebo texture_image_url přesahuje 20 MB.
- Neplatné Data URI: Řetězec base64 je poškozený.
- Neplatná kombinace parametrů: enable_pbr je podporováno pouze tehdy, je-li should_texture nastaveno na true.
- Nepodporovaný model pro low poly: ai_model: "meshy-6-lite" nepodporuje model_type: "lowpoly".
- Nepodporovaný model pro Ultra: geometry_resolution vyžaduje meshy-7.1 nebo latest.
- Nepodporovaný model pro možnosti obrázku: image_enhancement nebo remove_lighting je nastaveno s ai_model: "meshy-6-lite" nebo model_type: "smart-topology".
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/v1/image-to-3d

# Simple request with required params
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -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>"
  }'

# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -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>",
    "ai_model": "meshy-7.1",
    "geometry_resolution": "4k",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v1/image-to-3d/:id

Načtení úlohy Obrázek na 3D

Tento koncový bod umožňuje načíst úlohu Obrázek na 3D podle platného id úlohy. Podrobnosti o tom, jaké vlastnosti objekt úlohy Obrázek na 3D obsahuje, naleznete v části Objekt úlohy Obrázek na 3D.

Parametry

Name
id
Type
path
Description
Jedinečný identifikátor úlohy Obrázek na 3D, kterou chcete načíst.

Návratová hodnota

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

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "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=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "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": 30
}

DELETE/openapi/v1/image-to-3d/:id

Smazání úlohy Obrázek na 3D

Tento koncový bod trvale smaže úlohu Obrázek 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 Obrázek na 3D, kterou chcete smazat.

Stav úlohy

Úloha, která je stále ve stavu PENDING, je smazána a kredity spotřebované při vytvoření jsou vráceny.

Úlohu, která je již IN_PROGRESS, nelze smazat: požadavek je odmítnut s chybou 409 Conflict a úloha pokračuje v běhu. Kredity za úlohu, kterou již worker začal zpracovávat, nejsou vratné, takže smazání uprostřed běhu by vás stálo jak kredity, tak výsledek. Počkejte, až dosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a poté ji smažte.

Úloha v koncovém stavu (SUCCEEDED, FAILED nebo CANCELED) je smazána bez vrácení kreditů.

Návratové hodnoty

Vrací 200 OK v případě úspěchu, nebo 409 Conflict, pokud je úloha ve stavu IN_PROGRESS.

Request

DELETE

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

GET/openapi/v1/image-to-3d

Seznam úloh Obrázek na 3D

Tento koncový bod umožňuje načíst seznam úloh Obrázek na 3D.

Parametry

Volitelné atributy

Name
page_num
Type
integer
Description
Číslo stránky pro stránkování. Začíná a výchozí hodnota je 1.
Name
page_size
Type
integer
Description
Limit velikosti stránky. Výchozí hodnota je 10 položek. Maximální povolená hodnota je 100 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 Obrázek na 3D.

Request

GET

/openapi/v1/image-to-3d

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-3d",
    "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=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
      "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "thumbnail_urls": {
      "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
      "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
      "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
      "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
    },
    "texture_prompt": "",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "expires_at": 1692771679037,
    "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": 30
  }
]

GET/openapi/v1/image-to-3d/:id/stream

Streamování úlohy Obrázek na 3D

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

Parametry

Name
id
Type
path
Description
Jedinečný identifikátor úlohy Obrázek na 3D, kterou chcete streamovat.

Návratová hodnota

Vrací proud objektů úlohy Obrázek na 3D ve formě Server-Sent Events.

U úloh ve stavu PENDING nebo IN_PROGRESS bude datový proud odpovědi obsahovat pouze nezbytná pole progress a status.

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/image-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",
  "type": "image-to-3d",
  "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=***",
  "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=***",
  "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "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": 30
}

The Image to 3D Task Object

Objekt Image to 3D Task je pracovní jednotka, kterou Meshy sleduje za účelem generování 3D modelu ze vstupního obrázku. Objekt má následující vlastnosti:

Vlastnosti

Name
id
Type
string
Description
Jedinečný identifikátor úlohy. I když jako implementační detail používáme pro id úloh k-seřaditelné UUID, neměli byste si o formátu id dělat žádné předpoklady.
Name
type
Type
string
Description
Typ úlohy Image to 3D. Hodnota je image-to-3d.
Name
model_urls
Type
object
Description
Stažitelná URL adresa k souboru texturovaného 3D modelu vygenerovaného Meshy. Vlastnost pro daný formát bude vynechána, pokud daný formát nebyl vygenerován, místo vrácení prázdného řetězce.
- Name
  glb
  Type
  string
  Description
  Stažitelná URL adresa k souboru GLB.
- Name
  fbx
  Type
  string
  Description
  Stažitelná URL adresa k souboru FBX.
- Name
  obj
  Type
  string
  Description
  Stažitelná URL adresa k souboru OBJ.
- Name
  usdz
  Type
  string
  Description
  Stažitelná URL adresa k souboru USDZ.
- Name
  mtl
  Type
  string
  Description
  Stažitelná URL adresa k souboru MTL, vrácená spolu s exporty OBJ, pokud jsou přítomny textury.
- Name
  stl
  Type
  string
  Description
  Stažitelná URL adresa k souboru STL.
- Name
  3mf
  Type
  string
  Description
  Stažitelná URL adresa k souboru 3MF. Přítomno pouze pokud byl formát 3mf vyžádán prostřednictvím target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Stažitelná URL adresa k původnímu výstupnímu souboru GLB před remeshováním.
  Dostupné pouze v případě, že úloha byla vytvořena s should_remesh: true i save_pre_remeshed_model: true zároveň.
Name
thumbnail_url
Type
string
Description
Stažitelná URL adresa k miniatuře souboru modelu. Odpovídá thumbnail_urls.front, pokud je přítomna, zachováno kvůli zpětné kompatibilitě.
Name
alpha_thumbnail_url
Type
string
Description
Stažitelná URL adresa k 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
thumbnail_urls
Type
object
Description
Stažitelné URL adresy pro čtyři miniatury vygenerovaného 3D modelu ze základních světových stran. Každá hodnota je podepsaná URL adresa na PNG o rozměrech 512×512 vykreslené se stejnými materiály a osvětlením jako thumbnail_url. Užitečné pro náhled modelu z více úhlů v dávkových zpracováních bez nutnosti stahovat GLB.
Přítomno pouze v případě, že úloha byla vytvořena s multi_view_thumbnails: true a dosáhla stavu SUCCEEDED. Starší úlohy a úlohy vytvořené bez tohoto volitelného nastavení toto pole nebudou obsahovat.
- Name
  front
  Type
  string
  Description
  Pohled zepředu, rotace o 0° kolem svislé osy (odpovídá thumbnail_url).
- Name
  right
  Type
  string
  Description
  Pohled zprava, rotace o 90°.
- Name
  back
  Type
  string
  Description
  Pohled zezadu, rotace o 180°.
- Name
  left
  Type
  string
  Description
  Pohled zleva, rotace o 270°.
Name
texture_prompt
Type
string
Description
Textový prompt, který byl použit k řízení procesu texturování.
Name
texture_image_url
Type
string
Description
Stažitelná URL adresa k obrázku textury, který byl použit k řízení procesu texturování.
Name
ultra_mode
Type
boolean
⚠ zastaralé
Description
Zastaralé; místo toho použijte geometry_resolution.
Name
geometry_resolution
Type
string
Description
Úroveň Ultra, ve které úloha proběhla (2k nebo 4k); vynecháno pro standard.
Name
progress
Type
integer
Description
Postup úlohy. Pokud úloha ještě nebyla zahájena, tato vlastnost bude 0. Jakmile úloha uspěje, stane se 100.
Name
started_at
Type
timestamp
Description
Časové razítko, kdy byla úloha zahájena, v milisekundách. Pokud úloha ještě nebyla zahájena, tato vlastnost bude 0.
Časové razítko představuje počet milisekund, které uplynuly od 1. ledna 1970 UTC, podle normy 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, kdy byla úloha vytvořena, v milisekundách.
Name
expires_at
Type
timestamp
Description
Časové razítko, kdy vyprší platnost výsledku úlohy, v milisekundách.
Name
finished_at
Type
timestamp
Description
Časové razítko, kdy byla úloha dokončena, v milisekundách. Pokud úloha ještě nebyla 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 danou úlohou. Běžně 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 k obrázku mapy základní barvy.
- Name
  metallic
  Type
  string
  Description
  Stažitelná URL adresa k obrázku kovové mapy.
  Pokud je úloha vytvořena s enable_pbr: false, tato vlastnost bude vynechána.
- Name
  normal
  Type
  string
  Description
  Stažitelná URL adresa k obrázku 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 k obrázku 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 k obrázku mapy emise.
  Pokud je úloha vytvořena s enable_pbr: false, nebo pokud je ai_model nastaven na meshy-6-lite, meshy-7.1, meshy-t2 či latest, tato vlastnost bude vynechána.
Name
preceding_tasks
Type
integer
Description
Počet předchozích úloh.
Hodnota tohoto pole má smysl pouze tehdy, je-li stav úlohy PENDING.
Name
task_error
Type
object
Description
Podrobnosti o chybě u neúspěšných úloh. Úplný popis objektu task_error najdete v části 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 (v případě neúspěchu jsou kredity vráceny).

Example Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "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=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "texture_image_url": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "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": 30
}