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

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 API

Stwórz swój pierwszy model 3D za pomocą Meshy REST API w czterech krokach — od utworzenia klucza API aż po pobranie modelu.


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.

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


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

Poniższe przykłady używają tego samego zdjęcia. Aby wypróbować inny obraz, zmień image_url.

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

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
}

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.


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

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łóż 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


Następne kroki