Remesh API

Remesh API vám umožňuje remeshovat a exportovat existující 3D modely generované jinými Meshy API (jako Obrázek na 3D nebo Text na 3D) do různých formátů. Tato sekce poskytuje podrobnosti o tom, jak používat Remesh API.

POST/openapi/v1/remesh

Vytvoření úlohy Remesh

Tento koncový bod vytváří novou úlohu remesh.

Pro konverzi formátů a změnu velikosti použijte dedikované Convert API a Resize API. Zastaralé parametry níže budou nadále fungovat, ale doporučujeme nové koncové body pro nové integrace.

Parametry

Pouze jeden z input_task_id nebo model_url je požadován. Pokud jsou poskytnuty oba, 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 remeshovat. Tato úloha musí být jednou z následujících úloh: Text na 3D Náhled, Text na 3D Vylepšení, Obrázek na 3D nebo Retexturování. Navíc musí mít stav SUCCEEDED.

Name
model_url
Type
string
Povinné
Description
Poskytněte 3D model pro Meshy k remeshování prostřednictvím veřejně přístupného URL nebo data URI. Podporované formáty: .glb, .gltf, .obj, .fbx, .stl.
Pro Data URI použijte MIME type: application/octet-stream.

Name
target_formats
Type
string[]
výchozí ["glb"]
Description
Seznam cílových formátů pro remeshovaný model. Pokud není uvedeno, je generován pouze GLB.
Dostupné hodnoty: glb, fbx, obj, usdz, blend, stl, 3mf.
Name
topology
Type
string
výchozí triangle
Description
Určete topologii generovaného modelu.
Dostupné hodnoty:
- quad: Generovat síť s převahou čtyřúhelníků.
- triangle: Generovat decimovanou trojúhelníkovou síť.
Name
target_polycount
Type
integer
výchozí 30,000
Description
Určete cílový počet polygonů v generovaném modelu. Skutečný počet polygonů se může lišit od cíle v závislosti na složitosti geometrie.
Platný rozsah hodnot se liší v závislosti na úrovni uživatele:
- 100 až 300,000 (včetně)
Name
decimation_mode
Type
integer
Description
Povolit adaptivní decimaci nastavením úrovně počtu polygonů. Pokud je nastaveno, target_polycount je ignorován.
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
resize_height
Type
number
⚠ zastaralé
výchozí 0
Description
Změňte velikost modelu na určitou výšku měřenou v metrech. Doporučujeme použít dedikované Resize API místo toho.
auto_size, resize_height a resize_longest_side jsou vzájemně vylučující.
Name
resize_longest_side
Type
number
⚠ zastaralé
výchozí 0
Description
Změňte velikost modelu tak, aby nejdelší rozměr ohraničujícího boxu odpovídal zadané hodnotě v metrech. Doporučujeme použít dedikované Resize API místo toho.
auto_size, resize_height a resize_longest_side jsou vzájemně vylučující.
Name
auto_size
Type
boolean
⚠ zastaralé
výchozí false
Description
Pokud je nastaveno na true, služba používá AI vidění k automatickému odhadu skutečné výšky objektu a odpovídajícímu změnění velikosti modelu. Doporučujeme použít dedikované Resize API místo toho.
auto_size, resize_height a resize_longest_side jsou vzájemně vylučující.

Platí pouze když auto_size = true

Name
origin_at
Type
string
⚠ zastaralé
výchozí bottom
Description
Pozice počátku. Doporučujeme použít dedikované Resize API místo toho.
Dostupné hodnoty: bottom, center.

Name
convert_format_only
Type
boolean
⚠ zastaralé
Description
Pokud je true, služba změní pouze formát vstupního modelového souboru a ignoruje další vstupy jako topology, resize_height a target_polycount. Doporučujeme použít dedikované Convert API místo toho.
target_formats musí být poskytnuty, pokud je convert_format_only nastaveno na true.

Name
alpha_thumbnail
Type
boolean
výchozí false
Description
Pokud je nastaveno na true, úloha navíc vykreslí verzi náhledu s průhledným pozadím (RGBA) a vrátí ji jako alpha_thumbnail_url v odpovědi GET. Stávající pole thumbnail_url zůstává nezměněno.

Návratové hodnoty

Vlastnost result odpovědi obsahuje id nově vytvořené úlohy remesh.

Režimy selhání

Name
400 - Bad Request
Description
Požadavek byl nepřijatelný. Běžné příčiny:
- Chybějící parametr: Musí být poskytnuto buď model_url nebo input_task_id.
- 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.
- Nedosažitelné URL: model_url nemohlo být staženo.
- Neplatná topologie: Parametr topology je neplatný.
- Vzájemně vylučující parametry: auto_size a resize_height nemohou být oba nastaveny.
Name
401 - Unauthorized
Description
Autentizace selhala. Zkontrolujte prosím svůj API klíč.
Name
402 - Payment Required
Description
Nedostatečné kredity pro provedení této úlohy.
Name
429 - Too Many Requests
Description
Překročili jste svůj limit rychlosti.

Požadavek

POST

/openapi/v1/remesh

# Basic remesh with custom formats and resize
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "resize_height": 1.0,
    "origin_at": "bottom"
  }'

# Quad remesh with auto-size
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "auto_size": true
  }'

Odpověď

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/remesh/:id

Načtení úlohy Remesh

Tento koncový bod načítá úlohu remesh podle jejího ID.

Parametry

Name
id
Type
path
Description
ID úlohy remesh, kterou chcete načíst.

Vrací

Objekt úlohy Remesh.

Request

GET

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

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

DELETE/openapi/v1/remesh/:id

Smazat úlohu Remesh

Tento koncový bod trvale smaže úlohu remesh, včetně všech přidružených modelů a dat. Tato akce je nevratná.

Parametry cesty

Name
id
Type
path
Description
ID úlohy remesh, kterou chcete smazat.

Vrátí

Vrátí 200 OK při úspěchu.

Požadavek

DELETE

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

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

Odpověď

// Returns 200 Ok on success.

GET/openapi/v1/remesh

Seznam úkolů Remesh

Tento koncový bod vám umožňuje získat seznam úkolů Remesh.

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 pro řazení.
Dostupné hodnoty:
- +created_at: Řadit podle času vytvoření vzestupně.
- -created_at: Řadit podle času vytvoření sestupně.

Návraty

Vrací stránkovaný seznam Objektů úkolů Remesh.

Request

GET

/openapi/v1/remesh

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "remesh",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null
  }
]

GET/openapi/v1/remesh/:id/stream

Streamování úlohy Remesh

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

Parametry

Name
id
Type
path
Description
Jedinečný identifikátor pro úlohu Remesh ke streamování.

Vrací

Vrací stream Objektů úlohy Remesh jako Server-Sent Events.

Pro úlohy PENDING nebo IN_PROGRESS bude stream odpovědí zahrnovat pouze nezbytná pole progress a status.

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/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": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
    "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

Objekt úlohy Remesh

Objekt úlohy Remesh představuje pracovní jednotku, kterou Meshy používá k remeshingu a exportu existujícího 3D modelu do různých formátů. Objekt má následující vlastnosti:

Vlastnosti

Name
id
Type
string
Description
Unikátní identifikátor úlohy. I když používáme k-tříditelné UUID pro id úloh jako implementační detail, neměli byste dělat žádné předpoklady o formátu id.
Name
type
Type
string
Description
Typ úlohy Remesh. Hodnota je remesh.
Name
model_urls
Type
object
Description
Stahovatelná URL adresa k texturovanému 3D modelovému souboru generovanému Meshy. Vlastnost pro formát bude vynechána, pokud formát není generován, místo vrácení prázdného řetězce.
- Name
  glb
  Type
  string
  Description
  Stahovatelná URL adresa k souboru GLB.
- Name
  fbx
  Type
  string
  Description
  Stahovatelná URL adresa k souboru FBX.
- Name
  obj
  Type
  string
  Description
  Stahovatelná URL adresa k souboru OBJ.
- Name
  usdz
  Type
  string
  Description
  Stahovatelná URL adresa k souboru USDZ.
- Name
  blend
  Type
  string
  Description
  Stahovatelná URL adresa k souboru Blender.
- Name
  stl
  Type
  string
  Description
  Stahovatelná URL adresa k souboru STL.
- Name
  3mf
  Type
  string
  Description
  Stahovatelná URL adresa k souboru 3MF. Přítomna pouze, když byl 3mf požadován prostřednictvím target_formats.
Name
thumbnail_url
Type
string
Description
Stahovatelná URL adresa k náhledovému obrázku vykreslenému z remeshovaného modelu.
Name
alpha_thumbnail_url
Type
string
Description
Stahovatelná URL adresa k verzi thumbnail_url s průhledným pozadím (RGBA). Přítomna pouze, když byla úloha vytvořena s alpha_thumbnail: true a průhledný náhled byl úspěšně vykreslen; jinak je toto pole vynecháno.
Name
progress
Type
integer
Description
Progress úlohy. Pokud úloha ještě nezačala, tato vlastnost bude 0. Jakmile úloha uspěje, stane se 100.
Name
status
Type
string
Description
Stav úlohy. Možné hodnoty jsou jedna z PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
Name
preceding_tasks
Type
integer
Description
Počet předcházejících úloh.
Hodnota tohoto pole má smysl pouze, pokud je stav úlohy PENDING.
Name
created_at
Type
timestamp
Description
Časové razítko, kdy byla úloha vytvořena, v milisekundách.
Name
started_at
Type
timestamp
Description
Časové razítko, kdy byla úloha spuštěna, v milisekundách. Pokud úloha ještě nezačala, tato vlastnost bude 0.
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
task_error
Type
object
Description
Podrobnosti o chybě pro neúspěšné úlohy. Viz Chyby pro úplnou referenci objektu task_error.
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. Vrací 0 pro FAILED úlohy (kredity jsou při selhání vráceny).

Příklad objektu úlohy Remesh

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5
}