Remesh API

Rozhraní Remesh API vám umožňuje remeshovat a exportovat existující 3D modely vygenerované jinými rozhraní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 používat Remesh API.

POST/openapi/v1/remesh

Vytvoření úlohy Remesh

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

Pro převod formátu a změnu velikosti použijte dedikované Convert API a Resize API. Níže uvedené zastaralé parametry budou nadále funkční, 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 uvedeny oba, má input_task_id 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: Text na 3D Preview, Text na 3D Refine, Obrázek na 3D nebo Retexturování. Navíc musí mít stav SUCCEEDED.

Name
model_url
Type
string
Povinné
Description
Poskytněte prosím 3D model, který má Meshy remeshovat, pomocí veřejně přístupné URL adresy nebo data URI. Podporované formáty: .glb, .gltf, .obj, .fbx, .stl.
U 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 parametr vynecháte, vygeneruje se pouze GLB.
Dostupné hodnoty: glb, fbx, obj, usdz, blend, stl, 3mf.
Name
topology
Type
string
výchozí triangle
Description
Určuje topology vygenerovaného modelu.
Dostupné hodnoty:
- quad: Vygeneruje síť s dominantním podílem čtyřúhelníků (quad).
- triangle: Vygeneruje decimovanou trojúhelníkovou síť.
Name
target_polycount
Type
integer
výchozí 30,000
Description
Určuje cílový počet polygonů ve vygenerovaném modelu. Skutečný počet polygonů se může od cílové hodnoty 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, parametr 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ění velikost modelu na určitou výšku měřenou v metrech. Doporučujeme použít místo toho 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ámce (bounding box) odpovídal zadané hodnotě v metrech. Doporučujeme použít místo toho 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 použije AI vidění k automatickému odhadu skutečné výšky objektu v reálném světě a podle toho změní velikost modelu. Doporučujeme použít místo toho 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 použít místo toho dedikované Resize API.
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 ignoruje ostatní vstupy jako topology, resize_height a target_polycount. Doporučujeme použít místo toho dedikované Convert API.
Pokud je convert_format_only nastaveno na true, musí být uveden parametr target_formats.

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

Návratové hodnoty

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

Chybové stavy

Name
400 - Bad Request
Description
Požadavek byl nepřijatelný. Běžné příčiny:
- Chybějící parametr: Musí být uveden 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 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 nelze nastavit 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í této úlohy.
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

Smazat úlohu Remesh

Tento koncový bod trvale smaže úlohu remesh, včetně všech souvisejících modelů a dat. Tuto akci nelze vrátit zpět.

Parametry cesty

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

Stav úlohy

Úloha, která je stále ve stavu PENDING, je smazána a kredity spotřebované při jejím vytvoření jsou vráceny.

Úlohu, která je již ve stavu IN_PROGRESS, nelze smazat: požadavek je odmítnut s chybou 409 Conflict a úloha běží dál. Kredity za úlohu, kterou již worker začal zpracovávat, nejsou vratné, takže smazání za běhu by vás stálo kredity i výsledek zároveň. Počkejte, dokud úloha nedosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a teprve poté ji smažte.

Úloha v koncovém stavu (SUCCEEDED, FAILED nebo CANCELED) je smazána bez vrácení kreditů.

Návratové hodnoty

Vrací 200 OK v případě úspěchu, nebo 409 Conflict, pokud je úloha ve stavu IN_PROGRESS.

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

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left 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."
}

GET/openapi/v1/remesh

Seznam úkolů Remesh

Tento koncový bod 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á hodnota je 100 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ů úkolu 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, kterou chcete streamovat.

Návratová hodnota

Vrací proud objektů úlohy Remesh jako Server-Sent Events.

U úloh se stavem PENDING nebo IN_PROGRESS bude datový proud 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 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. 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
Stahovatelná URL adresa k texturovanému 3D souboru modelu vygenerovanému Meshy. Vlastnost pro daný formát bude vynechána, pokud daný formát nebyl vygenerová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řítomná pouze pokud 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řítomná pouze pokud 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 zahájena, tato vlastnost bude 0. Jakmile úloha uspěje, změní se 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 okamžiku vytvoření úlohy, v milisekundách.
Name
started_at
Type
timestamp
Description
Časové razítko okamžiku 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 okamžiku 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ě pro neúspěšné úlohy. Úplný popis objektu task_error naleznete v části Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů spotřebovaných touto úlohou. Přítomné, pokud je stav úlohy PENDING, IN_PROGRESS, nebo SUCCEEDED. Vrací 0 pro úlohy FAILED (kredity jsou při neúspěchu 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
}