Convert API

Převést 3D model do jiných souborových formátů, z úlohy Meshy nebo ze souboru modelu.

POST/openapi/v1/convert

Vytvoření úlohy Převést

Vytvoří úlohu Převést. Úloha běží na pozadí. Informace o tom, jak dlouho úloha obvykle trvá, najdete v části Doby zpracování.

Request

POST

/openapi/v1/convert

curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
  }'

Response

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

Parametry

Name
input_task_id
Type
string
Povinné
Description
Povinné, pokud neodešlete model_url. ID úlohy, která vytvořila 3D model, například úlohy Text na 3D, Obrázek na 3D, Remesh, Změnit velikost nebo Retexturování. Úloha musí pocházet z API a mít stav SUCCEEDED.

Name
model_url
Type
string
Povinné
Description
Povinné, pokud neodešlete input_task_id. Model k převodu, jako veřejná URL adresa nebo Data URI. Pokud odešlete obojí, Meshy použije input_task_id.
Model musí být soubor GLB, glTF, OBJ, FBX nebo STL o velikosti nejvýše 400 MB z adresy URL http nebo https, nebo 100 MB jako Data URI. Pro Data URI použijte MIME type application/octet-stream.
Soubor nad 100 MB musí navíc splňovat tato pravidla:
- Soubor GLB, glTF, FBX nebo OBJ může mít nejvýše 10 000 000 ploch. Meshy počítá plochy jako trojúhelníky, takže čtyřúhelník se počítá jako 2 a síť vykreslená vícekrát se počítá jednou pro každou kopii.
- Soubor FBX musí být binární FBX verze 7.1 nebo novější.
- Soubor GLB nebo glTF nesmí používat kompresi Draco.

Name
target_formats
Type
string[]
Povinné
Description
Formáty souborů, které se mají vygenerovat. Uveďte alespoň jeden. Chybějící nebo prázdný seznam vrátí 400.
Dostupné hodnoty:
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf

Návratové hodnoty

Pole result v odpovědi obsahuje ID nové úlohy Převést.

Režimy selhání

Name
400 - Bad Request
Description
Požadavek nelze spustit. Chybová zpráva uvádí, jaký problém byl zjištěn. Například:
- Chybějící parametr: Nebyl odeslán ani model_url, ani input_task_id.
- Chybějící target_formats: target_formats chybí nebo neobsahuje žádný formát.
- Neplatná vstupní úloha: input_task_id není úspěšná úloha API se souborem modelu.
- Neplatný formát modelu: Soubor model_url má nepodporovanou příponu.
- Nedostupná URL adresa: Meshy nemůže stáhnout soubor model_url.
- Příliš velký soubor modelu: Soubor model_url je větší než 400 MB z adresy URL http nebo https, nebo větší než 100 MB jako Data URI.
- Příliš mnoho ploch: Soubor model_url je větší než 100 MB a má více než 10 000 000 ploch. Snižte počet ploch a soubor odešlete znovu.
- ASCII FBX nad 100 MB: Soubor model_url je ASCII FBX větší než 100 MB. Odešlete jej jako binární FBX nebo GLB.
- Nečitelný soubor modelu: Soubor model_url je větší než 100 MB a Meshy nemůže přečíst jeho hlavičku. Například se jedná o GLB nebo glTF komprimovaný pomocí Draco, nebo o binární FBX starší než 7.1.
- Hlavička modelu je příliš složitá: Soubor model_url je větší než 100 MB a jeho hlavička obsahuje příliš mnoho sítí, uzlů nebo záznamů ke kontrole. Snižte počet objektů v souboru a odešlete jej znovu.
Opravte požadavek a odešlete jej znovu. Viz Chyby.
Name
401 - Unauthorized
Description
API klíč chybí nebo je neplatný. Zkontrolujte hlavičku Authorization.
Name
402 - Payment Required
Description
Například:
- Nedostatek kreditů: Účet nemá pro tuto úlohu dostatek kreditů nebo účet dosáhl limitu kreditů. Zkontrolujte svůj zůstatek kreditů a zkuste to znovu.
- Bezplatný plán: Vytvoření úlohy vyžaduje placený plán. Upgradujte svůj plán v nastavení předplatného a zkuste to znovu.
Name
403 - Forbidden
Description
input_task_id je reliéfní model, který tento koncový bod nedokáže převést. Zprávou je This model type does not support this operation. Odešlete jiný model.
Name
404 - Not Found
Description
input_task_id neodpovídá žádné z vašich úloh. Zkontrolujte ID úlohy a odešlete požadavek znovu.
Name
429 - Too Many Requests
Description
Překročili jste svůj limit rychlosti. Počkejte a zkuste to znovu. Viz Limity rychlosti.

GET/openapi/v1/convert/:id

Získání úlohy Převést

Vrátí úlohu Převést podle jejího ID.

Request

GET

/openapi/v1/convert/:id

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Parametry

Name
id
Type
path
Description
ID úlohy z odpovědi na vytvoření.

Návratová hodnota

Objekt úlohy Převést.

DELETE/openapi/v1/convert/:id

Smazat úlohu Převést

Trvale smaže úlohu Převést, včetně jejích modelů a dat. Smazání nelze vrátit zpět.

Request

DELETE

/openapi/v1/convert/:id

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/convert/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 keeps 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."
}

Parametry cesty

Name
id
Type
path
Description
ID úlohy, která má být smazána.

Stav úlohy

Smazání úlohy ve stavu PENDING vrátí kredity, které byly použity při jejím vytvoření.

Úlohu ve stavu IN_PROGRESS nelze smazat. Požadavek vrátí 409 Conflict a úloha dál běží. Meshy nevrací kredity za úlohu, která už byla spuštěna, takže její smazání by vás stálo jak kredity, tak výsledek. Počkejte, až dosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a poté ji smažte.

Smazání úlohy v konečném stavu (SUCCEEDED, FAILED nebo CANCELED) nevrací její kredity.

Návratové hodnoty

200 OK, pokud je úloha smazána, nebo 409 Conflict, pokud je úloha ve stavu IN_PROGRESS.

GET/openapi/v1/convert

Seznam úloh převodu (Convert)

Vrátí seznam vašich úloh Convert.

Request

GET

/openapi/v1/convert

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "convert",
    "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]

Parametry

Name
page_num
Type
integer
výchozí 1
Description
Číslo stránky, kterou chcete vrátit, až do 255. Vyšší hodnota vrátí 400.

Name
page_size
Type
integer
výchozí 10
Description
Počet úloh na stránku, až do 100.

Name
sort_by
Type
string
Description
Pořadí řazení.
Dostupné hodnoty:
- +created_at: od nejstarších
- -created_at: od nejnovějších

Návratová hodnota

Stránkovaný seznam objektů úlohy Convert.

GET/openapi/v1/convert/:id/stream

Streamování úlohy Convert

Streamuje aktualizace úlohy Convert jako Server-Sent Events (SSE).

Request

GET

/openapi/v1/convert/:id/stream

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

Response Stream

// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

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

Parametry

Name
id
Type
path
Description
ID úlohy z odpovědi na vytvoření.

Návratová hodnota

Proud objektů úlohy Convert jako Server-Sent Events.

Každá událost obsahuje celý objekt úlohy ve stejném tvaru, jaký vrací koncový bod Get. Dokud je úloha ve stavu PENDING nebo IN_PROGRESS, její výsledková pole ještě nemají hodnoty.

Objekt úlohy Převést

Objekt úlohy Převést popisuje jednu konverzi formátu 3D modelu. Obsahuje stav, progress a soubory modelu, když úloha uspěje.

Vlastnosti

Name
id
Type
string
Description
ID úlohy. Považujte ho za neprůhledný řetězec a nespoléhejte na jeho formát.
Name
type
Type
string
Description
Typ úlohy, vždy convert.
Name
model_urls
Type
object
Description
Adresy URL pro stažení převedeného modelu, jedna pro každý formát souboru. Adresy URL mají pouze formáty uvedené v target_formats. Formát, který jste nepožadovali, nemá klíč, místo prázdného řetězce.
Name
progress
Type
integer
Description
Kolik z úlohy je hotovo, v procentech. Je 0, dokud úloha nezačne, a 100, když uspěje.
Name
status
Type
string
Description
Stav úlohy, jeden z PENDING, IN_PROGRESS, SUCCEEDED, FAILED nebo CANCELED.
Name
preceding_tasks
Type
integer
Description
Počet úloh ve frontě před touto úlohou. Hodnota má smysl pouze, dokud je úloha ve stavu PENDING.
Name
created_at
Type
timestamp
Description
Čas vytvoření úlohy, v milisekundách Unixu.
Name
started_at
Type
timestamp
Description
Čas zahájení úlohy, v milisekundách Unixu. Je 0, dokud úloha nezačne.
Name
finished_at
Type
timestamp
Description
Čas dokončení úlohy, v milisekundách Unixu. Je 0, dokud úloha neskončí.
Name
expires_at
Type
timestamp
Description
Čas, kdy vyprší platnost adres URL pro stažení úlohy, v milisekundách Unixu. Je 0, dokud úloha neskončí.
Name
texture_urls
Type
array
Description
Adresy URL pro stažení textur modelu, když úloha uspěje: pole objektů, jeden pro každou sadu textur. Každý objekt má adresu URL base_color a může mít také adresy URL metallic, roughness, normal, emission a metallic_roughness. Je null, dokud úloha neuspěje, a prázdné pole, když model nemá žádné textury.
Name
task_error
Type
object
Description
Podrobnosti chyby, když úloha selže. Viz Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů, které úloha spotřebovala, což je 1 pro úlohu Převést. Je 0 pro úlohu se stavem FAILED.