API Remesh

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

POST/openapi/v1/remesh

Create a Remesh Task

Tento koncový bod vytvoří novou úlohu Remesh.

Pro převod formátu a změnu velikosti použijte vyhrazené API Převést a API Změnit velikost. Níže uvedené zastaralé parametry budou nadále fungovat, ale pro nové integrace doporučujeme nové koncové body.

Parametry

Vyžadován je pouze jeden z input_task_id nebo model_url. Pokud jsou zadány 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, u které chcete provést Remesh. Tato úloha musí být jednou z následujících úloh: Text to 3D Preview, Text to 3D Refine, Obrázek na 3D nebo Retexturování. Kromě toho musí mít stav SUCCEEDED.

Name
model_url
Type
string
Povinné
Description
Poskytněte prosím 3D model, u kterého má Meshy provést Remesh, prostřednictvím veřejně dostupné 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 model po Remesh. Pokud je vynechán, vygeneruje se pouze GLB.
Dostupné hodnoty: glb, fbx, obj, usdz, blend, stl, 3mf.
Name
topology
Type
string
výchozí triangle
Description
Určete topology vygenerovaného modelu.
Dostupné hodnoty:
- quad: Vygeneruje síť převážně ze čtyřúhelníků.
- triangle: Vygeneruje redukovanou trojúhelníkovou síť.
Name
target_polycount
Type
integer
výchozí 30,000
Description
Určete cílový počet polygonů ve vygenerovaném modelu. Skutečný počet polygonů se může od cíle lišit v závislosti na složitosti geometrie.
Platný rozsah hodnot se liší podle úrovně uživatele:
- 100 až 300 000 (včetně)
Name
decimation_mode
Type
integer
Description
Povolte adaptivní redukci nastavením úrovně počtu polygonů. Pokud je nastavena, 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
resize_height
Type
number
⚠ zastaralé
výchozí 0
Description
Změňte velikost modelu na určitou výšku měřenou v metrech. Doporučujeme místo toho použít vyhrazené API Změnit velikost.
auto_size, resize_height a resize_longest_side se vzájemně vylučují.
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 místo toho použít vyhrazené API Změnit velikost.
auto_size, resize_height a resize_longest_side se vzájemně vylučují.
Name
auto_size
Type
boolean
⚠ zastaralé
výchozí false
Description
Při nastavení na true služba použije AI vidění k automatickému odhadu reálné výšky objektu a podle toho změní velikost modelu. Doporučujeme místo toho použít vyhrazené API Změnit velikost.
auto_size, resize_height a resize_longest_side se vzájemně vylučují.

Platí pouze když auto_size = true

Name
origin_at
Type
string
⚠ zastaralé
výchozí bottom
Description
Poloha počátku. Doporučujeme místo toho použít vyhrazené API Změnit velikost.
Dostupné hodnoty: bottom, center.

Name
convert_format_only
Type
boolean
⚠ zastaralé
Description
Pokud je true, služba pouze změní formát vstupního souboru modelu a bude ignorovat jiné vstupy jako topology, resize_height a target_polycount. Doporučujeme místo toho použít vyhrazené API Převést.
target_formats musí být poskytnuto, pokud je convert_format_only nastaveno na true.

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ůstává beze změny.

Vrací

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 zadáno 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.
- Nedostupná URL: model_url se nepodařilo stáhnout.
- Neplatná topology: Parametr topology je neplatný.
- Vzájemně se vylučující parametry: auto_size a resize_height nelze nastavit současně.
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/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
  }'

Response

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

GET/openapi/v1/remesh/:id

Načíst úlohu Remesh

Tento koncový bod načte úlohu Remesh podle jejího ID.

Parametry

Name
id
Type
path
Description
ID úlohy Remesh, která se má 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

Odstranění úlohy Remesh

Tento koncový bod trvale odstraní ú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, která má být odstraněna.

Vrací

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

Request

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

Response

// Returns 200 Ok on success.

GET/openapi/v1/remesh

Vypsat úlohy Remesh

Tento koncový bod umožňuje načíst seznam úloh 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, podle kterého se má řadit.
Dostupné hodnoty:
- +created_at: Řadit podle času vytvoření vzestupně.
- -created_at: Řadit podle času vytvoření sestupně.

Návratová hodnota

Vrací stránkovaný seznam objektů úloh 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 úlohy Remesh v reálném čase pomocí Server-Sent Events (SSE).

Parametry

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

Návratová hodnota

Vrací stream objektů úlohy Remesh 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/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 provedení Remesh 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
Jedinečný identifikátor úlohy. I když 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 Remesh. Hodnota je remesh.
Name
model_urls
Type
object
Description
URL ke stažení souboru 3D modelu s texturami vygenerovaného službou Meshy. Vlastnost pro formát bude vynechána, pokud daný formát není vygenerován, místo aby se vrátil prázdný řetězec.
- 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
  blend
  Type
  string
  Description
  URL ke stažení souboru Blender.
- 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ž byl 3mf vyžádán prostřednictvím target_formats.
Name
thumbnail_url
Type
string
Description
URL ke stažení náhledového obrázku vykresleného z modelu po Remesh.
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ě vykreslen; 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 uspěje, bude mít hodnotu 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ředchozích úloh.
Hodnota tohoto pole má význam pouze v případě, že stav úlohy je PENDING.
Name
created_at
Type
timestamp
Description
Časové razítko vytvoření úlohy v milisekundách.
Name
started_at
Type
timestamp
Description
Časové razítko spuštění úlohy v milisekundách. Pokud úloha ještě nebyla spuštěna, tato vlastnost bude 0.
Name
finished_at
Type
timestamp
Description
Časové razítko dokončení úlohy 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. Ú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. U úloh FAILED vrací 0 (kredity jsou při selhání vráceny).

Example Remesh Task Object

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