Remesh API

Remesh API umožňuje remesh a export existujících 3D modelů vygenerovaných jinými API Meshy (jako Obrázek na 3D nebo Text na 3D) do různých formátů. Tato sekce obsahuje podrobnosti o tom, jak Remesh API používat.

POST/openapi/v1/remesh

Create a Remesh Task

Tento koncový bod vytvoří nový úkol remesh.

Pro konverzi formátu a změnu velikosti použijte dedikované Convert API a Resize API. Níže uvedené zastaralé parametry budou i nadále fungovat, ale pro nové integrace doporučujeme nové koncové body.

Parametry

Je vyžadován pouze jeden z parametrů input_task_id nebo model_url. Pokud jsou zadány oba, input_task_id má přednost.

Name
input_task_id
Type
string
Povinné
Description
ID dokončeného úkolu Obrázek na 3D nebo Text na 3D, který chcete remeshovat. Tento úkol musí být jedním z následujících: Text na 3D Preview, Text na 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 pro remeshování prostřednictvím Meshy, a to pomocí veřejně dostupné URL adresy 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í zadáno, vygeneruje se pouze GLB.
Dostupné hodnoty: glb, fbx, obj, usdz, blend, stl, 3mf.
Name
topology
Type
string
výchozí triangle
Description
Zadejte topology vygenerovaného modelu.
Dostupné hodnoty:
- quad: Vygeneruje síť s převahou čtyřúhelníků.
- triangle: Vygeneruje decimovanou trojúhelníkovou síť.
Name
target_polycount
Type
integer
výchozí 30,000
Description
Zadejte 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
Povolí adaptivní decimaci nastavením úrovně počtu polygonů. Pokud je nastaveno, target_polycount se ignoruje.
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ění velikost modelu na určitou výšku měřenou v metrech. Doporučujeme místo toho použít dedikované Resize API.
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ění velikost modelu tak, aby nejdelší rozměr ohraničujícího rámečku odpovídal zadané hodnotě v metrech. Doporučujeme místo toho použít dedikované Resize API.
auto_size, resize_height a resize_longest_side se vzájemně vylučují.
Name
auto_size
Type
boolean
⚠ zastaralé
výchozí false
Description
Pokud je nastaveno na true, služba pomocí AI vidění automaticky odhadne skutečnou výšku objektu ve světě a odpovídajícím způsobem změní velikost modelu. Doporučujeme místo toho použít dedikované Resize API.
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
Pozice počátku. Doporučujeme místo toho použít dedikované Resize API.
Dostupné hodnoty: bottom, center.

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

Name
alpha_thumbnail
Type
boolean
výchozí false
Description
Pokud je nastaveno na true, úkol 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.

Návratové hodnoty

Vlastnost result odpovědi obsahuje id nově vytvořeného úkolu 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án buď model_url, nebo input_task_id.
- Neplatný vstupní úkol: input_task_id musí odkazovat na úspěšný úkol z podporovaného modelu.
- Neplatný formát modelu: model_url odkazuje na soubor s nepodporovanou příponou.
- Nedostupná URL adresa: 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 nemohou být nastaveny současně.
Name
401 - Unauthorized
Description
Autentizace se nezdařila. Zkontrolujte prosím svůj API klíč.
Name
402 - Payment Required
Description
Nedostatek kreditů k provedení tohoto úkolu.
Name
429 - Too Many Requests
Description
Překročili jste 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

Získání úlohy Remesh

Tento koncový bod získá úlohu remesh podle jejího ID.

Parametry

Name
id
Type
path
Description
ID úlohy remesh, kterou chcete získat.

Návratová hodnota

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

Smazání úlohy Remesh

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

Parametry cesty

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

Návratová hodnota

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

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

Seznam úloh 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á hodnota je 50 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ů ú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 v reálném čase pro úlohu Remesh pomocí Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Jedinečný identifikátor úlohy Remesh, pro kterou se má spustit streamování.

Návratová hodnota

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

U úloh se stavem PENDING nebo IN_PROGRESS bude proud odpovědí 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 remeshování 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. Ačkoli jako implementační detail používáme pro id úlohy 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í texturovaného souboru 3D modelu vygenerovaného Meshy. Vlastnost pro daný formát bude vynechána, pokud daný formát nebyl vygenerován, namísto vrácení prázdného řetězce.
- 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řítomné pouze tehdy, když bylo 3mf požadováno prostřednictvím target_formats.
Name
thumbnail_url
Type
string
Description
URL ke stažení náhledového obrázku vykresleného z remeshovaného modelu.
Name
alpha_thumbnail_url
Type
string
Description
URL ke stažení verze thumbnail_url s průhledným pozadím (RGBA). Přítomné 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
Postup úlohy. Pokud úloha ještě nebyla zahájena, tato vlastnost bude 0. Jakmile úloha uspěje, hodnota se změní na 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 tehdy, pokud je stav úlohy 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 zahájení úlohy, v milisekundách. Pokud úloha ještě nebyla zahájena, tato vlastnost bude 0.
Name
finished_at
Type
timestamp
Description
Časové razítko dokončení úlohy, v milisekundách. Pokud úloha ještě nebyla dokončena, tato vlastnost bude 0.
Name
task_error
Type
object
Description
Podrobnosti o chybě u neúspěšných úloh. Úplnou referenci objektu task_error naleznete v části Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů spotřebovaných touto úlohou. Přítomné, když je stav úlohy PENDING, IN_PROGRESS nebo SUCCEEDED. Vrací 0 pro úlohy se stavem FAILED (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
}