lowpoly bude vyřazen 30. 10. 2026. Před těmito daty přejděte na jiný model, abyste předešli chybám požadavků. Zobrazit všechna ukončení podpory

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.


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íč.

Otevřete stránku API Keys v Developer Platform a poté vytvořte svůj klíč


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>"

Všechny následující příklady používají tuto fotografii. Chcete-li vyzkoušet jiný obrázek, změňte image_url.

Ukázková ilustrace fantasy postavy použitá jako vstup pro Obrázek na 3D v tomto průvodci
Ukázkový vstup

Request

POST
/openapi/v1/image-to-3d
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

GET
/openapi/v1/image-to-3d/:id
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.


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

model_urls.glb
curl -L "<model_urls.glb from the response above>" -o model.glb
Výsledný 3D model vygenerovaný z ukázkové fotografie fantasy postavy
Váš výsledek

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


Další kroky