Resize API

Změňte velikost 3D modelu na skutečnou velikost v metrech. Nastavte jeho výšku nebo délku jeho nejdelší strany, nebo nechte Meshy odhadnout skutečnou výšku objektu.

POST/openapi/v1/resize

Vytvoření úlohy Resize

Vytvoří úlohu Resize. Úloha běží na pozadí. Jak dlouho úloha obvykle trvá, zjistíte v části Doby zpracování.

Request

POST

/openapi/v1/resize

# Simple: resize to a specific height
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "resize_height": 1.8
  }'

# Advanced: resize longest side with custom origin
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb",
    "resize_longest_side": 2.0,
    "origin_at": "center"
  }'

Response

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

Parametry

Name
input_task_id
Type
string
Povinné
Description
Vyžadováno, pokud neodešlete model_url. ID úlohy, která vytvořila 3D model, například úlohy Text na 3D, Obrázek na 3D, Remesh nebo Retexturování. Úloha musí pocházet z API a musí mít stav SUCCEEDED. Meshy vrátí zvětšený/zmenšený model jako soubor GLB.

Name
model_url
Type
string
Povinné
Description
Vyžadováno, pokud neodešlete input_task_id. Model, jehož velikost chcete změnit, 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 URL adresy 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 za 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.
Soubor GLB, OBJ, FBX nebo STL si ve výsledku zachová svůj formát. Soubor .gltf nebo Data URI se vrátí jako GLB.

Odešlete přesně jeden z parametrů resize_height, resize_longest_side nebo auto_size. Pokud neodešlete žádný z nich nebo odešlete více než jeden, vrátí se 400.

Name
resize_height
Type
number
Description
Nová výška modelu v metrech, větší než 0. Záporná hodnota vrátí 400.

Name
resize_longest_side
Type
number
Description
Nová délka nejdelší strany modelu v metrech, větší než 0. Záporná hodnota vrátí 400. Meshy zachová poměr stran modelu.

Name
auto_size
Type
boolean
Description
Zda odhadnout skutečnou výšku objektu v reálném světě pomocí AI vidění a podle ní model zvětšit/zmenšit. Pokud nenastavíte origin_at, Meshy umístí počátek na spodní stranu.

Name
origin_at
Type
string
výchozí bottom
Description
Kam umístit počátek modelu po změně velikosti, bottom nebo center.

Návratové hodnoty

Pole result v odpovědi obsahuje ID nové úlohy Resize.

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í mode změny velikosti: Nebyl odeslán žádný z parametrů resize_height, resize_longest_side a auto_size.
- Vzájemně se vylučující parametry: Požadavek obsahuje více než jeden z parametrů resize_height, resize_longest_side a auto_size. Odešlete pouze jeden.
- Záporná velikost: resize_height nebo resize_longest_side je záporné.
- Neplatná vstupní úloha: input_task_id není úspěšná API úloha 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.
- Soubor modelu je příliš velký: Soubor model_url má přes 400 MB z URL adresy http nebo https, nebo přes 100 MB jako Data URI.
- Příliš mnoho ploch: Soubor model_url má přes 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 nad 100 MB. Odešlete jej jako binární FBX nebo GLB.
- Nečitelný soubor modelu: Soubor model_url má přes 100 MB a Meshy nemůže přečíst jeho hlavičku. Jde například o GLB nebo glTF komprimovaný pomocí Draco, nebo binární FBX starší než 7.1.
- Hlavička modelu je příliš složitá: Soubor model_url má přes 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á dostatek kreditů pro tuto úlohu, 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 model typu basreliéf, jehož velikost tento koncový bod nedokáže změnit. Zpráva zní 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 limit rychlosti. Počkejte a zkuste to znovu. Viz Limity rychlosti.

GET/openapi/v1/resize/:id

Získat úlohu Resize

Vrátí úlohu Resize podle jejího ID.

Request

GET

/openapi/v1/resize/:id

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "resize",
  "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?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 Resize.

DELETE/openapi/v1/resize/:id

Smazání úlohy Resize

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

Request

DELETE

/openapi/v1/resize/:id

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/resize/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á se má smazat.

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ále běží. Meshy nevrací kredity za úlohu, která už byla spuštěna, takže jejím smazáním byste přišli jak o kredity, tak o výsledek. Počkejte, až dosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a poté ji smažte.

Smazání úlohy ve finálním stavu (SUCCEEDED, FAILED nebo CANCELED) kredity nevrací.

Návratové hodnoty

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

GET/openapi/v1/resize

Seznam úloh Změnit velikost

Vrátí seznam vašich úloh Změnit velikost.

Request

GET

/openapi/v1/resize

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "resize",
    "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?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ž 100.

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

Návratová hodnota

Stránkovaný seznam objektů úlohy Změnit velikost.

GET/openapi/v1/resize/:id/stream

Streamování úlohy Změnit velikost

Streamuje aktualizace úlohy Změnit velikost jako Server-Sent Events (SSE).

Request

GET

/openapi/v1/resize/:id/stream

curl -N https://api.meshy.ai/openapi/v1/resize/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": "resize",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb?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 při vytvoření.

Návratová hodnota

Stream objektů úlohy Změnit velikost 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.

The Resize task object

Objekt úlohy Resize popisuje jedno změnění velikosti 3D modelu. Obsahuje stav, progress a soubor modelu, jakmile úloha uspěje.

Vlastnosti

Name
id
Type
string
Description
ID úlohy. Považujte jej za neprůhledný řetězec a nespoléhejte na jeho formát.
Name
type
Type
string
Description
Typ úlohy, vždy resize.
Name
model_urls
Type
object
Description
URL pro stažení souboru modelu se změněnou velikostí. U input_task_id je soubor vždy GLB. U model_url si soubor GLB, OBJ, FBX nebo STL zachová svůj formát a soubor .gltf nebo data URI se vrátí jako GLB.
Name
progress
Type
integer
Description
Jak velká část úlohy je hotová, v procentech. Je 0, dokud úloha nezačne, a 100, jakmile 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 před touto úlohou ve frontě. Hodnota má smysl pouze dokud je úloha ve stavu PENDING.
Name
created_at
Type
timestamp
Description
Čas vytvoření úlohy, v milisekundách unixového času.
Name
started_at
Type
timestamp
Description
Čas zahájení úlohy, v milisekundách unixového času. Je 0, dokud úloha nezačne.
Name
finished_at
Type
timestamp
Description
Čas dokončení úlohy, v milisekundách unixového času. Je 0, dokud úloha neskončí.
Name
expires_at
Type
timestamp
Description
Čas, kdy vyprší platnost URL adres pro stažení výsledků úlohy, v milisekundách unixového času. Je 0, dokud úloha neskončí.
Name
texture_urls
Type
array
Description
URL pro stažení textur modelu, jakmile úloha uspěje: pole objektů, jeden pro každou sadu textur. Každý objekt má URL base_color a může mít také URL metallic, roughness, normal, emission a metallic_roughness. Je null, dokud úloha neuspěje, a prázdné pole, pokud model nemá žádné textury.
Name
task_error
Type
object
Description
Podrobnosti o chybě, pokud úloha selže. Viz Chyby.
Name
consumed_credits
Type
integer
Description
Počet kreditů, které úloha spotřebovala, což je 1 pro úlohu Resize. U úlohy FAILED je to 0.