Obrázek na 3D API

Proměňte obrázek v 3D model, texturovaný nebo netexturovaný, ve formátech dle vašeho výběru. Odešlete obrázek, nebo použijte výstup úlohy Text na obrázek či Obrázek na obrázek.

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

Vytvoření úlohy Obrázek na 3D

Vytvoří úlohu Obrázek na 3D. Úloha běží na pozadí. Informace o tom, jak dlouho úloha obvykle trvá, najdete v části Doby zpracování.

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

# Textured with Meshy N1 from the input image
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",
    "texture_model": "meshy-n1"
  }'

Response

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

Parametry

Name
input_task_id
Type
string
Povinné
Description
Povinné, pokud neodešlete image_url. ID úlohy Text na obrázek nebo Obrázek na obrázek, jejíž obrázek chcete použít jako vstup. Úloha musí být vytvořena vámi přes API, musí mít stav SUCCEEDED a musí vytvořit přesně jeden obrázek.

Name
image_url
Type
string
Povinné
Description
Povinné, pokud neodešlete input_task_id. Obrázek, který chcete převést na 3D model, jako veřejně přístupná URL adresa nebo base64 kódovaná data URI, například data:image/jpeg;base64,<your base64-encoded image data>. Pokud odešlete obě, Meshy použije input_task_id.
Obrázek musí být soubor JPG, JPEG, PNG nebo WebP o velikosti maximálně 20 MB, s minimálně 32 pixely na každé straně a maximálně 178 956 970 pixely (šířka × výška).

Name
model_type
Type
string
výchozí standard
Description
Druh generované 3D sítě.
Dostupné hodnoty:
- standard: síť s vysokou úrovní detailu
- smart-topology: síť z modelu Smart Topology, který vyberete pomocí ai_model (meshy-t2 nebo meshy-t2.5)
S volbou smart-topology Meshy ignoruje should_remesh, save_pre_remeshed_model a decimation_mode a přijímá pouze topology: triangle.
Name
ai_model
Type
string
výchozí latest
Description
AI model, který generuje 3D model. Dostupné hodnoty závisí na model_type.
Standardní modely (model_type: standard):
- latest: Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7 (zastaralé): místo toho použijte meshy-7.1
Modely Smart Topology (model_type: smart-topology) vytvářejí trojúhelníky, v počtu stěn, který lze nastavit pomocí target_polycount:
- meshy-t2: čistší topology a nativně oddělené části
- meshy-t2.5 (výchozí): ostřejší detail pro herní assety
Name
geometry_resolution
Type
string
výchozí standard
Description
Průchod generování geometrie.
Dostupné hodnoty:
- standard
- 2k: spustí průchod Ultra při 2048³
- 4k: spustí průchod Ultra při 4096³, pro nejvyšší úroveň detailu povrchu
2k vyžaduje meshy-7.1, latest, nebo zastaralý meshy-7. 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 je stejné jako geometry_resolution: "2k".
Name
should_texture
Type
boolean
výchozí true
Description
Zda generovat textury. true vrátí texturovaný model, false přeskočí texturování a vrátí netexturovanou síť.

Platí pouze když should_texture = true

Name
texture_model
Type
string
výchozí depends on ai_model
Description
AI model, který texturuje 3D model, v rámci stejné úlohy. Pokud ho vynecháte, použije se výchozí texturovací model pro váš ai_model. Nemění to cenu v kreditech.
Dostupné hodnoty:
- meshy-7: Meshy 7, s PBR mapami a texturami až do 8K
- meshy-n1: Meshy N1, 2K textura základní barvy pouze z referenčních obrázků
- meshy-6-lite: Meshy 6 Lite, 2K textura za nejnižší cenu
- meshy-6: Meshy 6, pouze jako výchozí pro ai_model: meshy-6
Každý ai_model přijímá meshy-7, meshy-n1 a meshy-6-lite. Volba, kterou zvolený texturovací model nepodporuje, vrátí 400. S meshy-n1 selže úloha u vygenerovaného modelu nad 7 999 999 trojúhelníků a Meshy vrátí jeho kredity. S should_texture: false Meshy ignoruje texture_model, ale neznámá hodnota přesto vrátí 400.
Co jednotlivé texturovací modely dělají a který zvolit, najdete v části Modely.
Name
enable_pbr
Type
boolean
výchozí false
Description
Zda kromě základní barvy generovat také PBR mapy (metalíza, drsnost a normálová mapa). true vyžaduje should_texture: true a s should_texture: false vrací 400. S texture_model: meshy-n1 vrací true chybu 400.
Texturovací model Meshy 6 navíc generuje emisní mapu, s výjimkou texture_resolution: 8k.
Name
texture_resolution
Type
string
výchozí 2k
Description
Velikost textury základní barvy. Větší textura zachytí více povrchového detailu.
Dostupné hodnoty:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
4k a 8k vyžadují texturovací model Meshy 7 nebo Meshy 6 a s ostatními vrací 400. Při 8k Meshy nevytváří emisní mapu.
Name
hd_texture
Type
boolean
⚠ zastaralé
výchozí false
Description
Místo toho použijte texture_resolution. hd_texture: true je stejné jako texture_resolution: "4k". Pokud odešlete obě, Meshy použije texture_resolution.
Name
texture_prompt
Type
string
Description
Text, který řídí texturu, maximálně 800 znaků. Delší text vrací 400. S texture_model: meshy-n1 jeho odeslání vrací 400.
Name
texture_image_url
Type
string
Description
Obrázek, který řídí texturu, jako veřejně přístupná URL adresa nebo base64 kódovaná data URI, například data:image/jpeg;base64,<your base64-encoded image data>. Obrázek musí být soubor JPG, JPEG, PNG nebo WebP o velikosti maximálně 20 MB, s minimálně 32 pixely na každé straně a maximálně 178 956 970 pixely (šířka × výška).
Meshy řídí texturu pouze jedním z texture_prompt a texture_image_url. Pokud odešlete obě, Meshy použije texture_prompt. Cenu texturování v kreditech najdete v části Ceny.
S texture_model: meshy-n1 Meshy texturuje z tohoto obrázku jako z pohledu zepředu, nebo ze vstupního obrázku, pokud ho vynecháte.
Texturování z obrázku nemusí fungovat dobře, pokud se tvar obrázku výrazně liší od geometrie 3D modelu.

Name
should_remesh
Type
boolean
výchozí true (meshy-6-lite), false (other models)
Description
Zda spustit fázi remesh. Pro nejvyšší kvalitu 3D modelu nastavte na false.

Platí pouze když should_remesh = true

Name
topology
Type
string
výchozí triangle
Description
Typ stěn výsledné sítě po remeshi.
Dostupné hodnoty:
- quad: síť převážně ze čtyřúhelníků
- triangle: zjednodušená trojúhelníková síť
Výstup Smart Topology je pouze trojúhelníkový, takže quad s meshy-t2 nebo meshy-t2.5 vrací 400. S texture_model: meshy-n1 vrací quad chybu 400, pokud je model remeshován, což meshy-6-lite dělá ve výchozím nastavení.
Name
decimation_mode
Type
integer
Description
Adaptivní počet stěn podle úrovně. Pokud ho nastavíte, Meshy ignoruje target_polycount.
Dostupné hodnoty:
- 1: ultra
- 2: vysoká
- 3: střední
- 4: nízká
Name
save_pre_remeshed_model
Type
boolean
výchozí false
Description
Zda uložit i GLB model z fáze před remeshem. Meshy ho vrátí v model_urls.pre_remeshed_glb.

Name
target_polycount
Type
integer
Description
Cílový počet stěn. Výsledek se může od cíle lišit v závislosti na geometrii modelu.
Platí ve dvou samostatných případech:
- Remesh: Když je should_remesh nastaveno na true u modelu standard, Meshy zjednoduší síť přibližně na tento počet. Pokud nastavíte decimation_mode, Meshy ho použije a target_polycount ignoruje.
- Smart Topology: Když je model_type nastaveno na smart-topology a ai_model je meshy-t2 nebo meshy-t2.5, Meshy vygeneruje model s tímto počtem stěn. Žádný remesh neprobíhá a should_remesh není potřeba.
Rozsah a výchozí hodnota závisí na případu:
Případ Rozsah Výchozí hodnota
Remesh 100 až 300000 30000
meshy-t2 100 až 15000 4000
meshy-t2.5 100 až 30000 15000
Hodnota mimo rozsah vrací 400.

Případ	Rozsah	Výchozí hodnota
Remesh	`100` až `300000`	`30000`
`meshy-t2`	`100` až `15000`	`4000`
`meshy-t2.5`	`100` až `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ zastaralé
výchozí auto
Description
Vynechte ho, protože neovlivňuje výstup. Jeho hodnoty dříve řídily symetrii během generování:
- off: bez symetrie
- auto: symetrie zvolená na základě vstupní geometrie
- on: vynucená symetrie
Name
pose_mode
Type
string
výchozí ""
Description
Póza generovaného modelu.
Dostupné hodnoty:
- a-pose: póza A
- t-pose: póza T
- "" (prázdný řetězec): bez konkrétní pózy
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 nebo T.
Name
surface_mode
Type
string
⚠ zastaralé
Description
Místo toho použijte ai_model. Neovlivňuje výstup, protože model generování, který vybíral, byl vyřazen z provozu.
Přijímané hodnoty jsou organic a hard. Jakákoli jiná hodnota vrací 400.
Name
image_enhancement
Type
boolean
výchozí true
Description
Zda před generováním optimalizovat vstupní obrázek. false zachová přesný vzhled vstupního obrázku bez jakéhokoli stylového zpracování.
Funguje pouze s meshy-6, meshy-7.1 nebo latest. S meshy-6-lite nebo model_type: smart-topology vrací 400.
Name
remove_lighting
Type
boolean
výchozí true
Description
Zda odstranit odlesky a stíny z textury základní barvy. Výsledek je čistší a lépe funguje za vašeho vlastního osvětlení.
Má účinek pouze u texturovacího modelu Meshy 6, a texturovací model, který ho nepodporuje, vrací pro true chybu 400. S model_type: smart-topology, nebo s ai_model: meshy-6-lite a jeho výchozím texturovacím modelem, jeho odeslání vrací 400.
Name
moderation
Type
boolean
výchozí false
Description
Zda před generováním prověřit tyto vstupy kvůli škodlivému obsahu:
- image_url
- texture_image_url
- texture_prompt
Pokud Meshy zjistí škodlivý obsah, požadavek vrátí 400 a Meshy úlohu nevytvoří.
Name
target_formats
Type
string[]
Description
Formáty souborů, které se mají vygenerovat. Meshy vygeneruje a vrátí pouze formáty, které uvedete, což může úlohu zkrátit. Pokud ho vynecháte, Meshy vygeneruje všechny formáty kromě 3mf, který získáte pouze tehdy, pokud ho uvedete.
Dostupné hodnoty:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
auto_size
Type
boolean
výchozí false
Description
Zda pomocí AI vidění odhadnout skutečnou výšku objektu v reálném světě a přizpůsobit jí velikost modelu. Meshy umístí počátek dole, pokud nenastavíte origin_at.
Name
alpha_thumbnail
Type
boolean
výchozí false
Description
Zda vykreslit i náhled s průhledným pozadím (RGBA), vrácený v alpha_thumbnail_url při získání úlohy. thumbnail_url se nezmění.
Name
multi_view_thumbnails
Type
boolean
výchozí false
Description
Zda vykreslit i náhledy zepředu, zprava, zezadu a zleva, vrácené v thumbnail_urls při získání úlohy. thumbnail_url se nezmění a stále zobrazuje pohled zepředu. Tím se úloha prodlouží přibližně o 5 sekund.

Platí pouze když auto_size = true

Name
origin_at
Type
string
výchozí bottom
Description
Kam umístit počátek modelu, bottom nebo center.

Návratová hodnota

Pole result odpovědi obsahuje ID nové úlohy Obrázek na 3D.

Režimy selhání

Name
400 - Bad Request
Description
Požadavek nelze spustit. Chybová zpráva uvádí, jaký problém byl zjištěn. Například:
- Chybějící parametr: Nebyl odeslán ani image_url, ani input_task_id.
- Neplatná vstupní úloha: input_task_id není úspěšně dokončená (SUCCEEDED) úloha Text na obrázek nebo Obrázek na obrázek, která vytvořila přesně jeden obrázek.
- Neplatný formát obrázku: Obrázek image_url není soubor JPG, JPEG, PNG ani WebP.
- Nedostupná URL adresa: Meshy nemůže stáhnout obrázek z image_url, protože URL adresa vrací 404 nebo vyprší časový limit.
- Obrázek je příliš velký: Obrázek image_url nebo texture_image_url má velikost přes 20 MB.
- Neplatná velikost obrázku: Obrázek image_url nebo texture_image_url má kratší stranu než 32 pixelů, nebo více než 178 956 970 pixelů (šířka × výška).
- Neplatné Data URI: Řetězec base64 je chybně formátovaný.
- Neplatná kombinace parametrů: enable_pbr je true a should_texture je false.
- Nepodporovaný model pro Ultra: geometry_resolution je 2k nebo 4k s ai_model, který to neumí zpracovat.
- Nepodporovaný model pro volby obrázku: jeden z těchto případů:
  - image_enhancement byl odeslán s ai_model: "meshy-6-lite" nebo model_type: "smart-topology".
  - remove_lighting byl odeslán s model_type: "smart-topology", nebo s ai_model: "meshy-6-lite" a jeho výchozím texturovacím modelem.
- Neplatný texturovací model: texture_model není jednou z dostupných hodnot.
- Texturovací model není dostupný: texture_model je meshy-6 s jiným ai_model než meshy-6. Odešlete meshy-7, meshy-n1 nebo meshy-6-lite, nebo ho vynechte.
- Nepodporovaná volba pro texturovací model: Požadavek žádá texturovací model o volbu, kterou nepodporuje, například enable_pbr: true s meshy-n1 nebo texturu 4k s meshy-6-lite. Viz Modely.
Opravte požadavek a odešlete ho znovu. Viz Chyby.
Name
401 - Unauthorized
Description
API klíč chybí nebo je neplatný. Zkontrolujte hlavičku Authorization.
Name
402 - Payment Required
Description
Například:
- Nedostatek kreditů: Účet nemá dostatek kreditů na tuto úlohu, nebo účet dosáhl limitu kreditů. Zkontrolujte svůj zůstatek kreditů a zkuste to znovu.
- Bezplatný plán: Vytvoření úlohy vyžaduje placený plán. Upgradujte svůj plán v nastavení předplatného a poté to zkuste znovu.
Name
403 - Forbidden
Description
Moderace obsahu zablokovala prompt nebo vstupní obrázek. Změňte vstup a zkuste to znovu.
Name
404 - Not Found
Description
input_task_id neodpovídá žádné z vašich úloh. Zkontrolujte ID úlohy a odešlete požadavek znovu.
Name
429 - Too Many Requests
Description
Překročili jste limit rychlosti. Počkejte a zkuste to znovu. Viz Limity rychlosti.

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

Získání úlohy Obrázek na 3D

Vrátí úlohu Obrázek na 3D podle jejího ID.

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": null,
  "consumed_credits": 30
}

Parametry

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

Návratová hodnota

Objekt úlohy Obrázek na 3D.

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

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

Trvale smaže úlohu Obrázek na 3D, včetně jejích modelů a dat. Smazání nelze vrátit zpět.

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

Parametry cesty

Name
id
Type
path
Description
ID úlohy, která má být smazána.

Stav úlohy

Smazání úlohy ve stavu PENDING vrátí kredity použité při jejím vytvoření.

Úlohu ve stavu IN_PROGRESS nelze smazat. Požadavek vrátí 409 Conflict a úloha pokračuje v běhu. Meshy nevrací kredity za úlohu, která už byla spuštěna, takže její smazání by vás stálo jak kredity, tak výsledek. Počkejte, dokud úloha nedosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a teprve poté ji smažte.

Smazání úlohy v konečném stavu (SUCCEEDED, FAILED nebo CANCELED) kredity nevrací.

Návratové hodnoty

200 OK, pokud je úloha smazána, nebo 409 Conflict, pokud je úloha ve stavu IN_PROGRESS.

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

Seznam úloh Obrázek na 3D

Vrátí seznam vašich úloh 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": null,
    "consumed_credits": 30
  }
]

Parametry

Name
page_num
Type
integer
výchozí 1
Description
Číslo stránky, kterou chcete vrátit, až do 255. Vyšší hodnota vrátí 400.
Name
page_size
Type
integer
výchozí 10
Description
Počet úloh na stránku, až 100.
Name
sort_by
Type
string
Description
Pořadí řazení.
Dostupné hodnoty:
- +created_at: od nejstarších
- -created_at: od nejnovějších

Návratové hodnoty

Stránkovaný seznam objektů úlohy Obrázek na 3D.

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

Streamuje aktualizace úlohy Obrázek na 3D jako Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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": null,
  "consumed_credits": 30
}

Parametry

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

Návratová hodnota

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

Každá událost obsahuje celý objekt úlohy ve stejné podobě, jakou vrací koncový bod Get. Dokud je úloha ve stavu PENDING nebo IN_PROGRESS, její výsledková pole ještě nemají hodnoty.

The Image to 3D task object

Objekt úlohy Obrázek na 3D popisuje jedno generování 3D modelu z obrázku. Obsahuje stav, progress a soubory modelu, pokud je úloha úspěšná.

Vlastnosti

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": null,
  "consumed_credits": 30
}

Name
id
Type
string
Description
ID úlohy. Považujte jej za neprůhledný řetězec a nespoléhejte na jeho formát.
Name
type
Type
string
Description
Typ úlohy, vždy image-to-3d.
Name
model_urls
Type
object
Description
Odkazy ke stažení vygenerovaného 3D modelu, jeden pro každý formát souboru. Formát, který úloha nevygenerovala, nemá klíč, místo aby obsahoval prázdný řetězec.
- Name
  glb
  Type
  string
  Description
  Soubor GLB.
- Name
  fbx
  Type
  string
  Description
  Soubor FBX.
- Name
  obj
  Type
  string
  Description
  Soubor OBJ.
- Name
  usdz
  Type
  string
  Description
  Soubor USDZ.
- Name
  mtl
  Type
  string
  Description
  Soubor MTL, vrácený spolu se souborem OBJ, pokud má model textury.
- Name
  stl
  Type
  string
  Description
  Soubor STL.
- Name
  3mf
  Type
  string
  Description
  Soubor 3MF. Přítomen pouze tehdy, pokud target_formats obsahuje 3mf.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Soubor GLB z doby před remeshem. Přítomen pouze tehdy, pokud jste úlohu vytvořili s should_remesh: true i save_pre_remeshed_model: true zároveň.
Name
thumbnail_url
Type
string
Description
Odkaz ke stažení náhledového obrázku 3D modelu. Je-li přítomno thumbnail_urls, jde o stejný obrázek jako thumbnail_urls.front. Meshy jej ponechává kvůli zpětné kompatibilitě.
Name
alpha_thumbnail_url
Type
string
Description
Odkaz ke stažení verze thumbnail_url s průhledným pozadím (RGBA). Přítomno pouze tehdy, pokud jste úlohu vytvořili s alpha_thumbnail: true a Meshy vykreslilo průhledný náhled.
Name
thumbnail_urls
Type
object
Description
Odkazy ke stažení náhledů 3D modelu ze čtyř stran. Každá hodnota je podepsaná URL adresa na PNG o rozměru 512×512, vykreslená se stejnými materiály a osvětlením jako thumbnail_url. Použijte je k náhledu modelu z více úhlů, například v dávkovém zpracování, bez nutnosti stahovat soubor GLB.
Přítomno pouze tehdy, pokud jste úlohu vytvořili s multi_view_thumbnails: true a úloha dosáhla stavu SUCCEEDED. Úlohy vytvořené bez multi_view_thumbnails: true toto pole neobsahují.
- Name
  front
  Type
  string
  Description
  Pohled zepředu, při 0° kolem svislé osy. Odpovídá thumbnail_url.
- Name
  right
  Type
  string
  Description
  Pohled zprava, při 90°.
- Name
  back
  Type
  string
  Description
  Pohled zezadu, při 180°.
- Name
  left
  Type
  string
  Description
  Pohled zleva, při 270°.
Name
texture_prompt
Type
string
Description
Textový prompt, který řídil texturu.
Name
texture_image_url
Type
string
Description
Odkaz ke stažení obrázku, který řídil texturu.
Name
ultra_mode
Type
boolean
⚠ zastaralé
Description
Místo toho si přečtěte geometry_resolution.
Name
geometry_resolution
Type
string
Description
Úroveň Ultra, se kterou úloha běžela, 2k nebo 4k. Úloha úrovně standard toto pole neobsahuje.
Name
progress
Type
integer
Description
Kolik z úlohy je hotovo, v procentech. Hodnota je 0, dokud úloha nezačne, a 100, když je úspěšná.
Name
started_at
Type
timestamp
Description
Čas zahájení úlohy, v milisekundách unixového času. Hodnota je 0, dokud úloha nezačne.
Name
created_at
Type
timestamp
Description
Čas vytvoření úlohy, v milisekundách unixového času.
Name
expires_at
Type
timestamp
Description
Čas, kdy vyprší platnost výsledku úlohy, v milisekundách unixového času.
Name
finished_at
Type
timestamp
Description
Čas dokončení úlohy, v milisekundách unixového času. Hodnota je 0, dokud úloha neskončí.
Name
status
Type
string
Description
Stav úlohy, jeden z PENDING, IN_PROGRESS, SUCCEEDED, FAILED nebo CANCELED.
Name
texture_urls
Type
array
Description
Mapy textur vygenerované úlohou, jako pole objektů. Obvykle obsahuje jeden objekt s těmito poli:
- Name
  base_color
  Type
  string
  Description
  Odkaz ke stažení mapy základní barvy.
- Name
  metallic
  Type
  string
  Description
  Odkaz ke stažení mapy kovovosti. Toto pole chybí, pokud jste úlohu vytvořili s enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  Odkaz ke stažení normálové mapy. Toto pole chybí, pokud jste úlohu vytvořili s enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  Odkaz ke stažení mapy drsnosti. Toto pole chybí, pokud jste úlohu vytvořili s enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  Odkaz ke stažení mapy emise. Meshy ji zahrne pouze tehdy, pokud jste úlohu vytvořili se všemi z těchto nastavení:
  
  ai_model: meshy-6, s výchozím modelem textury
  
  enable_pbr: true
  
  hodnotou texture_resolution rovnou 2k nebo 4k
Name
preceding_tasks
Type
integer
Description
Počet úloh před touto úlohou ve frontě. Hodnota má smysl pouze tehdy, dokud je úloha ve stavu PENDING.
Name
task_error
Type
object
Description
Podrobnosti o chybě, pokud úloha selže. Hodnota je null, pokud stav není FAILED. Viz Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů, které úloha spotřebovala. Přítomno, pokud je stav PENDING, IN_PROGRESS nebo SUCCEEDED. U úlohy se stavem FAILED je hodnota 0, protože Meshy v případě selhání úlohy kredity vrací.