Швидкий старт
Почніть зі створення вашого API-ключа
Кожен запит у цьому посібнику потребує його. Створення ключа займає лічені секунди.
Створити ваш API-ключСтворіть вашу першу 3D-модель за допомогою REST API Meshy за чотири кроки: від створення API-ключа до завантаження моделі.
Використовуєте ШІ-помічника для написання коду? Щоб підключити Claude Code, Cursor, Windsurf чи інший MCP-клієнт до Meshy, перегляньте Інтеграцію зі ШІ. Для чат-агента без підтримки MCP використовуйте llms.txt.
1Отримайте ваш API-ключ
Створіть API-ключ на сторінці API Keys Платформи для розробників. Ви не зможете переглянути ключ знову після того, як залишите цей екран, тож зберігайте його в надійному місці. Надсилайте його в кожному запиті як Bearer-токен у заголовку Authorization. Див. Автентифікацію.
Для створення та керування API-ключами потрібен платний план. На безкоштовному плані ви не можете створювати власні ключі, а Playground використовує вбудований ключ для тестування.

Не зберігайте ключ у ваших скриптах. Натомість зберігайте його у змінній середовища, як показано в наступному кроці.
2Створіть завдання Зображення у 3D
Надішліть зображення до Зображення у 3D. Щоб натомість почати з текстового prompt або кількох фотографій, використовуйте Текст у 3D або Мульти-зображення у 3D.
Спочатку збережіть ваш ключ у змінній середовища:
Export your key
export MESHY_API_KEY="<your-api-key>"
Виконайте це у вашому терміналі (Terminal на macOS, Command Prompt або PowerShell на Windows), а не в браузері.
У наступних прикладах скрізь використовується це фото. Щоб спробувати інше зображення, змініть 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"
}'
3Перевірте статус завдання
Завдання виконується у фоновому режимі і зазвичай триває кілька хвилин. Отримуйте дані завдання з того самого endpoint, доки status не стане SUCCEEDED, FAILED або CANCELED. У наступному запиті замініть <task_id> на ID, який повернув крок 2. Між запитами чекайте стільки секунд, скільки вказано в заголовку Retry-After.
Про типові тривалості обробки та про те, як довго чекати, перш ніж здатися, див. Життєвий цикл завдання.
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
}
Якщо завдання завершується невдало, status стає FAILED, а task_error вказує причину. Виправте вхідні дані або створіть нове завдання. Див. Помилки.
Щоб отримувати сповіщення про завершення завдання замість опитування, передавайте завдання потоково або використовуйте webhook.
4Завантажте вашу модель
Файли знаходяться в model_urls попередньої відповіді. Кожен формат (GLB, FBX, OBJ, USDZ та STL) має підписаний URL, дійсний протягом обмеженого часу. Ви також можете вставити URL у ваш браузер, щоб завантажити файл.
Download
curl -L "<model_urls.glb from the response above>" -o model.glb

На всіх планах, крім Enterprise, Meshy зберігає файли протягом 3 днів. Завантажте потрібні файли до завершення цього терміну. Див. Зберігання ресурсів.
Зберіть усе разом
Цей скрипт створює завдання, чекає на його завершення та завантажує модель.
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');
Дослідіть типові робочі процеси
Персонаж, готовий до гри
Прикріпіть скелет до гуманоїдної сітки, щоб вона була готова до анімації в Unity чи Unreal.
Learn more →Сітка Smart Topology
Встановіть model_type на smart-topology для Зображення у 3D, щоб отримати чисту, готову до гри трикутну сітку.
Модель для 3D-друку
Конвертуйте готову модель у багатоколірний файл 3MF, готовий до нарізки на шари та друку.
Learn more →Наступні кроки
- Перегляньте всі кінцеві точки у довіднику API.
- Перш ніж переходити до продакшену, перевірте Ціни, Обмеження швидкості та Помилки.
- Слідуйте покроковим рецептам у Кулінарній книзі.