Rychlý start

Toto je referenční dokumentace API pro programovou interakci s Meshy.

Používáte AI asistenta pro programování? Podívejte se na naši stránku Integrace AI — nainstalujte Meshy MCP server pro přístup k volání nástrojů z Claude Code, Cursor, Windsurf a dalších nástrojů kompatibilních s MCP, nebo nasměrujte běžného chatovacího agenta na llms.txt.

Meshy API poskytuje jednoduché rozhraní pro generování 3D modelů a textur z textových promptů a obrázků. Postupujte podle tohoto průvodce a rychle začněte.

Vytvoření API klíče

Vytvořte API klíč na stránce nastavení API zde, který použijete k bezpečné autentizaci svých požadavků. Formát API klíče je msy-<random-string>.

Vygenerovat API klíč

Jakmile API klíč vygenerujete, uložte ho na bezpečné místo.

API klíč testovacího režimu

Během vývoje a testování můžete použít náš API klíč testovacího režimu k prozkoumání API bez spotřeby svých kreditů:

msy_dummy_api_key_for_test_mode_12345678

Tento speciální API klíč má následující vlastnosti:

Lze ho použít k odesílání požadavků na všechny koncové body Meshy API
Při použití tohoto klíče se nespotřebovávají žádné kredity
Všechny platné požadavky vrátí stejné ukázkové výsledky úloh bez ohledu na vstupní parametry
Struktura dat odpovědi bude přesně odpovídat produkčnímu API
Ideální pro testování vaší integrace API před přepnutím na váš skutečný API klíč

API klíč testovacího režimu je určen pouze pro vývojové účely. Pro produkční použití prosím použijte svůj vlastní API klíč.

Vytvoření prvního API požadavku "Text na 3D"

V tomto příkladu vygenerujeme 3D model z textového promptu pomocí text-to-3d koncového bodu. Proces zahrnuje dvě fáze: fázi náhledu a fázi zpřesnění. Ve fázi náhledu se vygeneruje základní síť bez aplikované textury, což vám umožní vyhodnotit geometrii. Ve fázi zpřesnění se síť náhledu otexturuje na základě textového promptu.

Ukážeme vám, jak tyto požadavky provést ve skriptu Python.

Náhled

Meshy poskytuje sadu REST API endpointů. Můžete je používat s libovolným HTTP klientem podle svého výběru. Bez ohledu na to, které API voláte, API klíč se vždy předává jako hlavička s názvem Authorization. Před použitím tohoto skriptu nezapomeňte exportovat svůj API klíč jako proměnnou prostředí s názvem MESHY_API_KEY.

Klíčové parametry požadavku na náhled jsou mode, který je vždy "preview", a prompt, popis modelu, který potřebujete. V tomto příkladu jsme také zadali should_remesh, ale je volitelný.

api_request.py

import requests
import os
import time

headers = {
  "Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"
}

# 1. Generate a preview model and get the task ID

generate_preview_request = {
  "mode": "preview",
  "prompt": "a monster mask",
  "should_remesh": True,
}

generate_preview_response = requests.post(
  "https://api.meshy.ai/openapi/v2/text-to-3d",
  headers=headers,
  json=generate_preview_request,
)

generate_preview_response.raise_for_status()

preview_task_id = generate_preview_response.json()["result"]

print("Preview task created. Task ID:", preview_task_id)

Tím je volání API pro náhled dokončeno.

Mějte prosím na paměti, že Meshy API používá model asynchronního provádění, což znamená, že když vytvoříte úlohu, koncový bod API vrátí pouze ID úlohy. Poté musíte pomocí tohoto ID opakovaně dotazovat koncový bod stavu úlohy a zkontrolovat, zda byla úloha dokončena.

api_request.py

# 2. Poll the preview task status until it's finished

preview_task = None

while True:
  preview_task_response = requests.get(
    f"https://api.meshy.ai/openapi/v2/text-to-3d/{preview_task_id}",
    headers=headers,
  )

  preview_task_response.raise_for_status()

  preview_task = preview_task_response.json()

  if preview_task["status"] == "SUCCEEDED":
    print("Preview task finished.")
    break

  print("Preview task status:", preview_task["status"], "| Progress:", preview_task["progress"], "| Retrying in 5 seconds...")
  time.sleep(5)

Jakmile bude úloha dokončena, budete mít přístup k URL modelu z její odpovědi. Stáhněme model z pole model_urls v odpovědi.

api_request.py

# 3. Download the preview model in glb format

preview_model_url = preview_task["model_urls"]["glb"]

preview_model_response = requests.get(preview_model_url)
preview_model_response.raise_for_status()

with open("preview_model.glb", "wb") as f:
  f.write(preview_model_response.content)

print("Preview model downloaded.")

Pokud zatím vše funguje, váš preview_model.glb by měl vypadat podobně jako tento. Nebude to přesná shoda kvůli přirozené náhodnosti v AI pipeline.

Model náhledu

Zpřesnění

Přejděme k fázi zpřesnění. Chcete-li zahájit požadavek na zpřesnění, zadejte ID úlohy náhledu jako vstupní parametr.

api_request.py

# 4. Generate a refined model and get the task ID

generate_refined_request = {
  "mode": "refine",
  "preview_task_id": preview_task_id,
}

generate_refined_response = requests.post(
  "https://api.meshy.ai/openapi/v2/text-to-3d",
  headers=headers,
  json=generate_refined_request,
)

generate_refined_response.raise_for_status()

refined_task_id = generate_refined_response.json()["result"]

print("Refined task created. Task ID:", refined_task_id)

# 5. Poll the refined task status until it's finished

refined_task = None

while True:
  refined_task_response = requests.get(
    f"https://api.meshy.ai/openapi/v2/text-to-3d/{refined_task_id}",
    headers=headers,
  )

  refined_task_response.raise_for_status()

  refined_task = refined_task_response.json()

  if refined_task["status"] == "SUCCEEDED":
    print("Refined task finished.")
    break

  print("Refined task status:", refined_task["status"], "| Progress:", refined_task["progress"], "| Retrying in 5 seconds...")
  time.sleep(5)

# 6. Download the refined model in glb format

refined_model_url = refined_task["model_urls"]["glb"]

refined_model_response = requests.get(refined_model_url)
refined_model_response.raise_for_status()

with open("refined_model.glb", "wb") as f:
  f.write(refined_model_response.content)

print("Refined model downloaded.")

3D model refined_model.glb je nyní plně otexturovaný ✨.

Zpřesněný model

Dát vše dohromady

Zde je kompletní kód pro použití API Text na 3D.

api_request.py

import requests
import os
import time

headers = {
  "Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"
}

# 1. Generate a preview model and get the task ID

generate_preview_request = {
  "mode": "preview",
  "prompt": "a monster mask",
  "should_remesh": True,
}

generate_preview_response = requests.post(
  "https://api.meshy.ai/openapi/v2/text-to-3d",
  headers=headers,
  json=generate_preview_request,
)

generate_preview_response.raise_for_status()

preview_task_id = generate_preview_response.json()["result"]

print("Preview task created. Task ID:", preview_task_id)

# 2. Poll the preview task status until it's finished

preview_task = None

while True:
  preview_task_response = requests.get(
    f"https://api.meshy.ai/openapi/v2/text-to-3d/{preview_task_id}",
    headers=headers,
  )

  preview_task_response.raise_for_status()

  preview_task = preview_task_response.json()

  if preview_task["status"] == "SUCCEEDED":
    print("Preview task finished.")
    break

  print("Preview task status:", preview_task["status"], "| Progress:", preview_task["progress"], "| Retrying in 5 seconds...")
  time.sleep(5)

# 3. Download the preview model in glb format

preview_model_url = preview_task["model_urls"]["glb"]

preview_model_response = requests.get(preview_model_url)
preview_model_response.raise_for_status()

with open("preview_model.glb", "wb") as f:
  f.write(preview_model_response.content)

print("Preview model downloaded.")

# 4. Generate a refined model and get the task ID

generate_refined_request = {
  "mode": "refine",
  "preview_task_id": preview_task_id,
}

generate_refined_response = requests.post(
  "https://api.meshy.ai/openapi/v2/text-to-3d",
  headers=headers,
  json=generate_refined_request,
)

generate_refined_response.raise_for_status()

refined_task_id = generate_refined_response.json()["result"]

print("Refined task created. Task ID:", refined_task_id)

# 5. Poll the refined task status until it's finished

refined_task = None

while True:
  refined_task_response = requests.get(
    f"https://api.meshy.ai/openapi/v2/text-to-3d/{refined_task_id}",
    headers=headers,
  )

  refined_task_response.raise_for_status()

  refined_task = refined_task_response.json()

  if refined_task["status"] == "SUCCEEDED":
    print("Refined task finished.")
    break

  print("Refined task status:", refined_task["status"], "| Progress:", refined_task["progress"], "| Retrying in 5 seconds...")
  time.sleep(5)

# 6. Download the refined model in glb format

refined_model_url = refined_task["model_urls"]["glb"]

refined_model_response = requests.get(refined_model_url)
refined_model_response.raise_for_status()

with open("refined_model.glb", "wb") as f:
  f.write(refined_model_response.content)

print("Refined model downloaded.")

Zkopírujte a vložte kód do skriptu Python a spusťte ho.

Run the script

python api_request.py

Ve svém terminálu byste měli vidět výstup podobný následujícímu:

Spustit skript

Další kroky

Chcete si nejprve vyzkoušet endpointy bez psaní kódu? Použijte API Playground ke konfiguraci a spuštění požadavku a poté zkopírujte vygenerovaný snippet.
Kompletní referenční dokumentaci API najdete v sekci "API endpointy", která poskytuje podrobné informace o každém API.
Prozkoumejte podrobnosti o Cenách, limitech četnosti a o tom, jak řešit běžné chyby.
Nezapomeňte pravidelně sledovat náš Changelog, kde najdete aktualizace a opravy chyb.
Máte zpětnou vazbu nebo řešíte problémy? Připojte se k naší Discord komunitě - rádi od vás uslyšíme!