Rychlý start
Začněte vytvořením svého API klíče
Každý požadavek v tomto průvodci jej vyžaduje. Vytvoření klíče zabere pár sekund.
Vytvořit API klíčVytvořte svůj první 3D model pomocí Meshy REST API ve čtyřech krocích, od vytvoření API klíče až po stažení modelu.
Používáte AI asistenta pro programování? Pro připojení Claude Code, Cursor, Windsurf nebo jiného MCP klienta k Meshy se podívejte na Integrace AI. Pro chatovacího agenta bez podpory MCP použijte llms.txt.
1Získejte svůj API klíč
Vytvořte API klíč na stránce API Keys v Developer Platform. Jakmile tuto obrazovku opustíte, klíč už znovu nezobrazíte, proto si jej bezpečně uložte. Posílejte jej v každém požadavku jako Bearer token v hlavičce Authorization. Viz Autentizace.
K vytváření a správě API klíčů potřebujete placený plán. V rámci plánu Free si nemůžete vytvořit vlastní klíče a Playground pro testování používá vestavěný klíč.

Klíč nenechávejte ve svých skriptech. Místo toho jej uložte do proměnné prostředí, jak ukazuje další krok.
2Vytvořte úlohu Obrázek na 3D
Odešlete obrázek do Obrázek na 3D. Pokud chcete začít z textového promptu nebo z několika fotografií, použijte místo toho Text na 3D nebo Více obrázků na 3D.
Nejprve si uložte svůj klíč do proměnné prostředí:
Export your key
export MESHY_API_KEY="<your-api-key>"
Spusťte toto ve svém terminálu (Terminal na macOS, Command Prompt nebo PowerShell na Windows), ne v prohlížeči.
Všechny následující příklady používají tuto fotografii. Chcete-li vyzkoušet jiný obrázek, změňte image_url.

Request
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${MESHY_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://docs.meshy.ai/images/api/quick-start/source-photo.webp"
}'
3Zkontrolujte stav úlohy
Úloha běží na pozadí a obvykle trvá několik minut. Dotazujte se na stejný koncový bod, dokud status nebude SUCCEEDED, FAILED nebo CANCELED. V následujícím požadavku nahraďte <task_id> ID, které vrátil krok 2. Mezi požadavky čekejte počet sekund uvedený v hlavičce Retry-After.
Typické doby zpracování a dobu, po které byste to měli vzdát, najdete v sekci Životní cyklus úlohy.
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d/<task_id> \
-H "Authorization: Bearer ${MESHY_API_KEY}"
Response: SUCCEEDED
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"status": "SUCCEEDED",
"progress": 100,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"task_error": null
}
Pokud úloha selže, status bude FAILED a task_error uvede důvod. Opravte vstup nebo vytvořte novou úlohu. Viz Chyby.
Pokud chcete být o dokončení úlohy informováni místo opakovaného dotazování, streamujte úlohu nebo použijte webhook.
4Stáhněte si svůj model
Soubory jsou uvedeny v model_urls předchozí odpovědi. Každý formát (GLB, FBX, OBJ, USDZ a STL) má podepsanou URL adresu, která je platná po omezenou dobu. URL adresu můžete také vložit do prohlížeče a soubor tak stáhnout.
Download
curl -L "<model_urls.glb from the response above>" -o model.glb

Ve všech plánech kromě Enterprise uchovává Meshy soubory po dobu 3 dnů. Stáhněte si potřebné soubory do té doby. Viz Uchování assetů.
Dejte to všechno dohromady
Tento skript vytvoří úlohu, počká na její dokončení a stáhne model.
Full script
import axios from 'axios';
import fs from 'fs';
const headers = { Authorization: `Bearer ${process.env.MESHY_API_KEY}` };
const imageUrl = 'https://docs.meshy.ai/images/api/quick-start/source-photo.webp';
// 1. Create the task
const { data: created } = await axios.post(
'https://api.meshy.ai/openapi/v1/image-to-3d',
{ image_url: imageUrl },
{ headers, timeout: 60_000 },
);
const taskId = created.result;
// 2. Poll until it finishes, for up to 60 minutes
const deadline = Date.now() + 60 * 60 * 1000;
let task;
while (true) {
const { data, headers: resHeaders } = await axios.get(
`https://api.meshy.ai/openapi/v1/image-to-3d/${taskId}`,
{ headers, timeout: 30_000 },
);
task = data;
if (['SUCCEEDED', 'FAILED', 'CANCELED'].includes(task.status)) break;
if (Date.now() > deadline) {
// The task is still running. Check it again later with the same task ID instead of creating a new one.
throw new Error(`Task ${taskId} is still ${task.status}; check it again later`);
}
const waitSeconds = Number(resHeaders['retry-after']) || 5;
await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
}
// 3. Download the result (only if the task succeeded)
if (task.status !== 'SUCCEEDED') {
throw new Error(`Task ${task.status}: ${task.task_error?.message || 'unknown error'}`);
}
const { data: model } = await axios.get(task.model_urls.glb, { responseType: 'arraybuffer' });
fs.writeFileSync('model.glb', model);
console.log('Saved model.glb');
Prozkoumejte běžné pracovní postupy
Postava připravená pro hru
Opatřete humanoidní síť kostrou, aby byla připravená k animaci v Unity nebo Unreal.
Learn more →Síť Smart Topology
Nastavte model_type na smart-topology u Obrázek na 3D pro čistou trojúhelníkovou síť připravenou pro hry.
Model pro 3D tisk
Převeďte hotový model do vícebarevného souboru 3MF, připraveného k nařezání a tisku.
Learn more →Další kroky
- Prohlédněte si všechny koncové body v referenci API.
- Než přejdete do produkčního provozu, podívejte se na Ceny, Omezení rychlosti a Chyby.
- Postupujte podle návodů krok za krokem v Cookbooku.