Szybki start
Zacznij od utworzenia klucza API
Każde żądanie w tym przewodniku go potrzebuje. Utworzenie klucza zajmuje kilka sekund.
Utwórz swój klucz APIStwórz swój pierwszy model 3D za pomocą Meshy REST API w czterech krokach — od utworzenia klucza API aż po pobranie modelu.
Korzystasz z asystenta kodowania AI? Aby połączyć Claude Code, Cursor, Windsurf lub inny klient MCP z Meshy, zobacz Integracja z AI. W przypadku agenta czatu bez obsługi MCP użyj llms.txt.
1Uzyskaj swój klucz API
Utwórz klucz API na stronie API Keys w Developer Platform. Po opuszczeniu tego ekranu nie będzie można ponownie wyświetlić klucza, więc zapisz go w bezpiecznym miejscu. Wysyłaj go w każdym żądaniu jako token Bearer w nagłówku Authorization. Zobacz Uwierzytelnianie.
Aby tworzyć i zarządzać kluczami API, potrzebujesz płatnego planu. W planie Free nie możesz tworzyć własnych kluczy, a Playground korzysta z wbudowanego klucza do testów.

Nie umieszczaj klucza w swoich skryptach. Zamiast tego zapisz go w zmiennej środowiskowej, jak pokazano w następnym kroku.
2Utwórz zadanie Obraz na 3D
Wyślij obraz do Obraz na 3D. Aby zamiast tego zacząć od promptu tekstowego lub kilku zdjęć, użyj Tekst na 3D lub Wiele obrazów na 3D.
Najpierw zapisz swój klucz w zmiennej środowiskowej:
Export your key
export MESHY_API_KEY="<your-api-key>"
Uruchom to w terminalu (Terminal na macOS, Wiersz polecenia lub PowerShell na Windows), a nie w przeglądarce.
Poniższe przykłady używają tego samego zdjęcia. Aby wypróbować inny obraz, zmień 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"
}'
3Sprawdź status zadania
Zadanie działa w tle i zwykle zajmuje kilka minut. Pobieraj zadanie z tego samego punktu końcowego, aż status będzie równy SUCCEEDED, FAILED lub CANCELED. W poniższym żądaniu zastąp <task_id> identyfikatorem zwróconym w kroku 2. Między żądaniami odczekaj liczbę sekund podaną w nagłówku Retry-After.
Typowe czasy przetwarzania oraz informacje o tym, jak długo czekać, zanim się poddasz, znajdziesz w Cyklu życia zadania.
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
}
Jeśli zadanie zakończy się niepowodzeniem, status będzie równy FAILED, a task_error wyjaśni przyczynę. Popraw dane wejściowe lub utwórz kolejne zadanie. Zobacz Błędy.
Aby otrzymywać powiadomienie o zakończeniu zadania zamiast odpytywania, strumieniuj zadanie lub użyj webhooka.
4Pobierz swój model
Pliki znajdują się w polu model_urls poprzedniej odpowiedzi. Każdy format (GLB, FBX, OBJ, USDZ i STL) ma podpisany adres URL, który działa przez ograniczony czas. Możesz też wkleić adres URL do przeglądarki, aby pobrać plik.
Download
curl -L "<model_urls.glb from the response above>" -o model.glb

W każdym planie poza Enterprise Meshy przechowuje pliki przez 3 dni. Pobierz potrzebne pliki przed upływem tego czasu. Zobacz Przechowywanie zasobów.
Złóż to wszystko w całość
Ten skrypt tworzy zadanie, czeka na jego zakończenie i pobiera 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');
Poznaj typowe przepływy pracy
Postać gotowa do gry
Dodaj szkielet do siatki humanoidalnej (rigging), aby była gotowa do animacji w Unity lub Unreal.
Learn more →Siatka Smart Topology
Ustaw model_type na smart-topology dla Obraz na 3D, aby uzyskać czystą, gotową do gry siatkę trójkątów.
Model do druku 3D
Konwertuj gotowy model na wielokolorowy plik 3MF, gotowy do cięcia na warstwy i druku.
Learn more →Następne kroki
- Przeglądaj każdy punkt końcowy w Dokumentacji API.
- Zanim przejdziesz do produkcji, sprawdź Cennik, Limity zapytań oraz Błędy.
- Postępuj zgodnie z przepisami krok po kroku w Cookbooku.