Démarrage rapide

Créez votre premier modèle 3D avec l'API REST de Meshy en quatre étapes, de la création d'une clé API au téléchargement du modèle.

1Obtenez votre clé API

Créez une clé API sur la page API Keys de la Developer Platform. Vous ne pouvez plus consulter la clé une fois que vous avez quitté cet écran, conservez-la donc en lieu sûr. Envoyez-la dans chaque requête sous forme de jeton Bearer dans l'en-tête Authorization. Voir Authentification.

Vous avez besoin d'un plan payant pour créer et gérer des clés API. Avec le plan gratuit, vous ne pouvez pas créer vos propres clés, et le Playground utilise une clé intégrée à des fins de test.

2Créer une tâche Image en 3D

Envoyez une image à Image to 3D. Pour partir d'un prompt textuel ou de plusieurs photos à la place, utilisez Text to 3D ou Multi-Image to 3D.

Tout d'abord, stockez votre clé dans une variable d'environnement :

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

Les exemples suivants utilisent tous cette photo. Pour essayer une autre image, modifiez image_url.

Copy image URL

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

3Vérifier le statut de la tâche

La tâche s'exécute en arrière-plan et prend généralement quelques minutes. Récupérez la tâche depuis le même point de terminaison jusqu'à ce que status soit SUCCEEDED, FAILED ou CANCELED. Dans la requête suivante, remplacez <task_id> par l'ID renvoyé à l'étape 2. Entre les requêtes, attendez le nombre de secondes indiqué dans l'en-tête Retry-After.

Pour connaître les temps de traitement habituels, et combien de temps attendre avant d'abandonner, consultez Cycle de vie d'une tâche.

curl https://api.meshy.ai/openapi/v1/image-to-3d/<task_id> \
  -H "Authorization: Bearer ${MESHY_API_KEY}"

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

Si la tâche échoue, status vaut FAILED, et task_error indique pourquoi. Corrigez l'entrée ou créez une autre tâche. Voir Erreurs.

4Téléchargez votre modèle

Les fichiers se trouvent dans model_urls de la réponse précédente. Chaque format (GLB, FBX, OBJ, USDZ et STL) dispose d'une URL signée valable pendant une durée limitée. Vous pouvez également coller l'URL dans votre navigateur pour télécharger le fichier.

curl -L "<model_urls.glb from the response above>" -o model.glb

Tout assembler

Ce script crée la tâche, attend qu'elle se termine, puis télécharge le modèle.

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

Découvrir les flux de travail courants

Étapes suivantes

• Parcourez tous les points de terminaison dans la référence API.
• Avant de passer en production, consultez Tarification, Limites de débit et Erreurs.
• Suivez des recettes étape par étape dans le Cookbook.