API pro Retexturování

API pro Retexturování je funkce, která vám umožňuje integrovat možnosti retexturování pomocí AI od Meshy do vlastní aplikace. V této části najdete všechny informace, které potřebujete, abyste s tímto API mohli začít.

POST/openapi/v1/retexture

Vytvoření úlohy Retexturování

Tento koncový bod vám umožňuje vytvořit novou úlohu Retexturování. Viz Objekt úlohy Retexturování, kde najdete, které vlastnosti jsou zahrnuty v objektu úlohy Retexturování.

Parametry

Vyžadováno je pouze jedno z input_task_id nebo model_url. Pokud jsou zadány obě, input_task_id má prioritu.

Name
input_task_id
Type
string
Povinné
Description
ID dokončené úlohy Obrázek na 3D nebo Text na 3D, kterou chcete retexturovat. Tato úloha musí být jednou z následujících úloh: Text na 3D Preview, Text na 3D Refine, Obrázek na 3D nebo Remesh. Navíc musí mít stav SUCCEEDED.

Name
model_url
Type
string
Povinné
Description
Poskytněte Meshy 3D model k vytvoření textury. Podporované formáty: .glb, .gltf, .obj, .fbx, .stl.
Model lze poskytnout dvěma způsoby:
- Veřejně dostupná URL: URL, která je dostupná z veřejného internetu.
- Data URI: Base64 kódované data URI modelu. Použijte MIME type application/octet-stream. Příklad: data:application/octet-stream;base64,<your base64-encoded model data>.

Vyžadováno je pouze jedno z text_style_prompt nebo image_style_url. Pokud jsou zadány obě, image_style_url má prioritu.

Name
text_style_prompt
Type
string
Povinné
Description
Popište požadovaný styl textury objektu pomocí textu. Maximálně 600 znaků.

Name
image_style_url
Type
string
Povinné
Description
Poskytněte 2D obrázek, který bude sloužit jako vodítko pro proces texturování. Aktuálně podporujeme formáty .jpg, .jpeg a .png.
Obrázek lze poskytnout dvěma způsoby:
- Veřejně dostupná URL: URL, která je dostupná z veřejného internetu
- Data URI: Base64 kódované Data URI obrázku. Příklad data URI: data:image/jpeg;base64,<your base64-encoded image data>
Texturování podle obrázku nemusí fungovat optimálně, pokud jsou mezi původním assetem a nahraným obrázkem výrazné rozdíly v geometrii.

Name
ai_model
Type
string
výchozí latest
Description
ID modelu AI, který se použije pro retexturování. Dostupné hodnoty: meshy-5, meshy-6, latest (Meshy 6).
Name
enable_original_uv
Type
boolean
výchozí false
Description
Zachovat stávající UV rozvržení modelu místo generování nového.
- Pokud retexturujete model, který vygeneroval Meshy (prostřednictvím input_task_id nebo model_url, která odkazuje na výstup Meshy), nastavte tuto hodnotu na true, aby se znovu použilo jeho optimalizované UV rozvržení.
- Pokud retexturujete nahraný model třetí strany, nastavte true, pokud již má kvalitní UV, která chcete zachovat, nebo ponechte false, aby Meshy vytvořil nové UV rozbalení (nejlepší pro modely, které nemají správné UV mapování).
Name
enable_pbr
Type
boolean
výchozí false
Description
Vygeneruje PBR mapy (metallic, roughness, normal) kromě základní barvy. Emisní mapa je také zahrnuta, když je ai_model meshy-6 nebo latest.
Name
hd_texture
Type
boolean
výchozí false
Description
Vygeneruje texturu základní barvy v rozlišení 4K (4096×4096) pro vyšší úroveň detailů.
Podporováno pouze tehdy, když je ai_model meshy-6 nebo latest. PBR mapy se vždy generují ve 2K.
Name
remove_lighting
Type
boolean
výchozí true
Description
Odstraní odlesky a stíny z textury základní barvy, čímž vytvoří čistší výsledek, který lépe funguje při vlastních nastaveních osvětlení.
Podporováno pouze tehdy, když je ai_model meshy-6 nebo latest.
Name
target_formats
Type
string[]
Description
Určuje, které formáty 3D souborů mají být zahrnuty ve výstupu. Vygenerují a vrátí se pouze požadované formáty, což může zkrátit dobu dokončení úlohy. Pokud je vynecháno, jsou zahrnuty všechny podporované formáty.
Dostupné hodnoty: glb, obj, fbx, stl, usdz, 3mf
Pokud je vynecháno, vygenerují se všechny formáty kromě 3mf. 3mf je zahrnut pouze tehdy, když je výslovně zadán.
Name
alpha_thumbnail
Type
boolean
výchozí false
Description
Při nastavení na true úloha navíc vykreslí verzi náhledu s průhledným pozadím (RGBA) a vrátí ji jako alpha_thumbnail_url v odpovědi GET. Stávající pole thumbnail_url zůstane beze změny.

Návratová hodnota

Vlastnost result v odpovědi obsahuje id nově vytvořené úlohy Retexturování.

Režimy selhání

Name
400 - Bad Request
Description
Požadavek nebyl přijatelný. Běžné příčiny:
- Chybějící parametr: Musí být zadáno buď model_url, nebo input_task_id.
- Chybějící styl: Musí být zadáno buď text_style_prompt, nebo image_style_url.
- Neplatná vstupní úloha: input_task_id musí odkazovat na úspěšnou úlohu z podporovaného modelu.
- Neplatný formát modelu: model_url odkazuje na soubor s nepodporovanou příponou.
- Nedostupná URL: model_url nebo image_style_url se nepodařilo stáhnout.
Name
401 - Unauthorized
Description
Autentizace se nezdařila. Zkontrolujte 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/retexture

# Retexture with text prompt
curl https://api.meshy.ai/openapi/v1/retexture \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "https://cdn.meshy.ai/model/example_model_2.glb",
    "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style",
    "enable_original_uv": true,
    "enable_pbr": true
  }'

# Retexture with image style and PBR
curl https://api.meshy.ai/openapi/v1/retexture \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "https://cdn.meshy.ai/model/example_model_2.glb",
    "image_style_url": "https://cdn.meshy.ai/image/example_image.jpg",
    "ai_model": "latest",
    "enable_pbr": true,
    "enable_original_uv": true
  }'

Response

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

GET/openapi/v1/retexture/:id

Načtení úlohy Retexturování

Tento koncový bod umožňuje načíst úlohu Retexturování na základě platného id úlohy. Podívejte se na Objekt úlohy Retexturování, kde zjistíte, které vlastnosti jsou zahrnuty v objektu úlohy Retexturování.

Parametry

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

Vrací

Odpověď obsahuje objekt úlohy Retexturování. Podrobnosti najdete v části Objekt úlohy Retexturování.

Request

GET

/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "retexture",
  "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=***",
    "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=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style",
  "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"
    }
  ],
  "task_error": {

    "message": ""

  },

  "consumed_credits": 10
}

DELETE/openapi/v1/retexture/:id

Odstranit úlohu Retexturování

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

Parametry cesty

Name
id
Type
path
Description
ID úlohy Retexturování, která má být odstraněna.

Návratová hodnota

Při úspěchu vrací 200 OK.

Request

DELETE

/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/retexture

Seznam úloh Retexturování

Tento koncový bod umožňuje načíst seznam úloh Retexturování.

Parametry

Name
page_num
Type
integer
výchozí 1
Description
Číslo stránky pro stránkování.
Name
page_size
Type
integer
výchozí 10
Description
Limit velikosti stránky. Maximální povolený počet je 50 položek.
Name
sort_by
Type
string
Description
Pole, podle kterého se má řadit.
Dostupné hodnoty:
- +created_at: Seřadit podle času vytvoření vzestupně.
- -created_at: Seřadit podle času vytvoření sestupně.

Vrací

Vrací stránkovaný seznam objektů úloh Retexturování.

Request

GET

/openapi/v1/retexture

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "retexture",
    "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=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style",
    "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": 10
  }
]

GET/openapi/v1/retexture/:id/stream

Streamování úlohy Retexturování

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

Parametry

Name
id
Type
path
Description
Jedinečný identifikátor úlohy Retexturování, která se má streamovat.

Vrací

Vrací stream objektů úlohy Retexturování jako Server-Sent Events.

U úloh PENDING nebo IN_PROGRESS bude stream odpovědi obsahovat pouze nezbytná pole progress a status.

Request

GET

/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578/stream

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

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "retexture",
  "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=***",
    "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=***",
    "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=***"
  },
  "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": 10
}

Objekt úlohy Retexturování

Objekt úlohy Retexturování je pracovní jednotka, kterou Meshy používá ke generování 3D textury buď z textových, nebo obrazových vstupů. Model má následující vlastnosti:

Vlastnosti

Name
id
Type
string
Description
Jedinečný identifikátor úlohy. Přestože jako implementační detail používáme pro id úloh k-sortovatelné UUID, neměli byste dělat žádné předpoklady o formátu id.
Name
type
Type
string
Description
Typ úlohy Retexturování. Hodnota je retexture.
Name
model_urls
Type
object
Description
URL ke stažení souboru texturovaného 3D modelu vygenerovaného službou Meshy.
- Name
  glb
  Type
  string
  Description
  URL ke stažení souboru GLB.
- Name
  fbx
  Type
  string
  Description
  URL ke stažení souboru FBX.
- Name
  obj
  Type
  string
  Description
  URL ke stažení souboru OBJ.
- Name
  usdz
  Type
  string
  Description
  URL ke stažení souboru USDZ.
- Name
  mtl
  Type
  string
  Description
  URL ke stažení souboru MTL, vráceného společně s exporty OBJ, když jsou přítomny textury.
- Name
  stl
  Type
  string
  Description
  URL ke stažení souboru STL.
- Name
  3mf
  Type
  string
  Description
  URL ke stažení souboru 3MF. Přítomno pouze tehdy, když bylo 3mf vyžádáno prostřednictvím target_formats.
Name
text_style_prompt
Type
string
Description
Toto je textový prompt, který byl použit k vytvoření úlohy texturování.
Name
image_style_url
Type
string
Description
Toto je vstupní obrázek, který byl použit k vytvoření úlohy texturování.
Name
thumbnail_url
Type
string
Description
URL ke stažení obrázku miniatury souboru modelu.
Name
alpha_thumbnail_url
Type
string
Description
URL ke stažení verze thumbnail_url s průhledným pozadím (RGBA). Přítomno pouze tehdy, když byla úloha vytvořena s alpha_thumbnail: true a průhledný náhled byl úspěšně vyrenderován; jinak je toto pole vynecháno.
Name
progress
Type
integer
Description
progress úlohy. Pokud úloha ještě nebyla spuštěna, tato vlastnost bude 0. Jakmile úloha úspěšně skončí, změní se na 100.
Name
started_at
Type
timestamp
Description
Časové razítko, kdy byla úloha spuštěna, v milisekundách. Pokud úloha ještě nebyla spuštěna, tato vlastnost bude 0.
Časové razítko představuje počet milisekund uplynulých od 1. ledna 1970 UTC podle standardu 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ě není dokončena, tato vlastnost bude 0.
Name
status
Type
string
Description
Stav úlohy. Možné hodnoty jsou jedna z PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Pole objektů URL textur, které jsou vygenerovány z úlohy. Obvykle obsahuje pouze jeden objekt URL textury. Každá URL textury má následující vlastnosti:
- Name
  base_color
  Type
  string
  Description
  URL ke stažení obrázku mapy základní barvy.
- Name
  metallic
  Type
  string
  Description
  URL ke stažení obrázku metalické mapy.
  Pokud je úloha vytvořena s enable_pbr: false, tato vlastnost bude vynechána.
- Name
  normal
  Type
  string
  Description
  URL ke stažení obrázku normálové mapy.
  Pokud je úloha vytvořena s enable_pbr: false, tato vlastnost bude vynechána.
- Name
  roughness
  Type
  string
  Description
  URL ke stažení obrázku mapy drsnosti.
  Pokud je úloha vytvořena s enable_pbr: false, tato vlastnost bude vynechána.
- Name
  emission
  Type
  string
  Description
  URL ke stažení obrázku emisní mapy.
  Pokud je úloha vytvořena s enable_pbr: false, nebo je ai_model meshy-5, tato vlastnost bude vynechána.
Name
preceding_tasks
Type
integer
Description
Počet předcházejících úloh.
Tato vlastnost je přítomna pouze tehdy, když je stav úlohy PENDING.
Name
task_error
Type
object
Description
Podrobnosti o chybě pro neúspěšné úlohy. Úplnou referenci objektu task_error najdete v části Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů spotřebovaných touto úlohou. Přítomno, když je stav úlohy PENDING, IN_PROGRESS nebo SUCCEEDED. Pro úlohy FAILED vrací 0 (kredity jsou při selhání vráceny).

Example Retexture Task Model

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "retexture",
  "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=***"
  },
  "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style",
  "image_style_url": "https://assets.meshy.ai/***/image/example_image.jpg?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "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": 10
}