lowpoly zostanie wycofany 30 paź 2026. Zmień model przed tymi datami, aby uniknąć błędów żądań.

Szybki start

Zacznij od utworzenia klucza API

Każde żądanie w tym przewodniku go wymaga. Utworzenie klucza zajmuje kilka sekund.

Utwórz swój klucz API

Cztery kroki do uzyskania Twojego pierwszego modelu 3D przy użyciu Meshy REST API.


1Uzyskaj swój klucz API

Utwórz klucz API na stronie API Keys w Developer Platform — po zamknięciu tego ekranu nie będzie można go ponownie wyświetlić, więc przechowuj go w bezpiecznym miejscu. Każde żądanie uwierzytelnia się za pomocą tokenu Bearer w nagłówku Authorization — zobacz Authentication.

Otwórz stronę API Keys w Developer Platform, a następnie utwórz swój klucz


2Wykonaj swoje pierwsze żądanie Obraz na 3D

Wyeksportuj swój klucz, a następnie utwórz swoje pierwsze zadanie za pomocą Obraz na 3D. Pracujesz na podstawie promptu tekstowego lub wielu zdjęć? Zobacz Tekst na 3D lub Wiele obrazów na 3D.

Export your key

export MESHY_API_KEY="<your-api-key>"

Każdy poniższy przykład wykorzystuje to zdjęcie — podstaw własny adres image_url, aby wypróbować coś innego.

Przykładowa ilustracja postaci fantasy użyta jako wejście Obraz na 3D w tym przewodniku
Przykładowe wejście

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

3Sprawdź status zadania

Zadanie działa w tle i zwykle trwa kilka minut. Odpytuj ten sam punkt końcowy, aż status będzie równy SUCCEEDED, FAILED lub CANCELED, zastępując poniżej <task_id> identyfikatorem zwróconym w kroku 2. Typowe czasy oraz informacje, jak długo czekać, znajdziesz w Cyklu życia zadania.

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": {
    "message": ""
  }
}

4Pobierz swój model

Pobierz model z model_urls w powyższej odpowiedzi. Każdy format (GLB, FBX, OBJ, USDZ, STL) to podpisany, ograniczony czasowo URL — możesz też pominąć wiersz poleceń i wkleić URL bezpośrednio w pasku adresu przeglądarki, aby go pobrać.

Download

model_urls.glb
curl -L "<model_urls.glb from the response above>" -o model.glb
Wynikowy model 3D wygenerowany z przykładowego zdjęcia postaci fantasy
Twój wynik

Złóżmy to wszystko w całość

Wolisz jeden skrypt, który robi wszystko naraz — tworzy zadanie, odpytuje o jego stan i pobiera wynik?

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');

Explore common workflows


Kolejne kroki

  • Wolisz interfejs graficzny? Otwórz Developer Platform — uruchamiaj zapytania w Playground, śledź użycie i logi zapytań oraz zarządzaj webhookami.
  • Przejrzyj pełne API reference, aby poznać każdy punkt końcowy.
  • Ucz się na działających przykładach: śledź krok po kroku przepisy w Cookbook i czytaj samouczki oraz historie realizacji projektów na Developer Blog.
  • Zanim przejdziesz do produkcji, zapoznaj się z sekcjami Cennik, Rate Limits i Błędy.
  • Śledź dziennik zmian, aby być na bieżąco z aktualizacjami i poprawkami błędów.
  • Masz uwagi lub napotkałeś problemy? Dołącz do naszej społeczności na Discord — chętnie Cię wysłuchamy!