lowpoly sera retiré le 30 oct. 2026. Changez de modèle avant ces dates pour éviter les erreurs de requête.

Démarrage rapide

Commencez par créer votre clé API

Chaque requête de ce guide en nécessite une. Créer une clé ne prend que quelques secondes.

Créer votre clé API

Quatre étapes pour obtenir votre premier modèle 3D, en utilisant l'API REST Meshy.


1Obtenez votre clé API

Créez une clé API depuis la page API Keys de la Developer Platform — vous ne pourrez plus la consulter après cet écran, alors conservez-la en lieu sûr. Chaque requête s'authentifie avec un jeton Bearer dans l'en-tête Authorization — voir Authentication.

Ouvrez la page API Keys dans la Developer Platform, puis créez votre clé


2Effectuez votre première requête Image en 3D

Exportez votre clé, puis créez votre première tâche avec Image to 3D. Vous préférez travailler à partir d'un prompt texte ou de plusieurs photos ? Consultez Text to 3D ou Multi-Image to 3D.

Export your key

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

Chaque exemple ci-dessous utilise cette photo — remplacez par votre propre image_url pour essayer autre chose.

Sample fantasy character illustration used as the Image to 3D input in this guide
Sample input

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

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. Interrogez le même point de terminaison jusqu'à ce que status soit SUCCEEDED, FAILED ou CANCELED, en remplaçant <task_id> ci-dessous par l'ID renvoyé à l'étape 2. Pour connaître les durées habituelles et le temps d'attente recommandé, consultez Cycle de vie d'une tâche.

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

4Téléchargez votre modèle

Récupérez le modèle depuis model_urls dans la réponse ci-dessus. Chaque format (GLB, FBX, OBJ, USDZ, STL) est une URL signée et limitée dans le temps — ou passez outre la ligne de commande et collez directement l'URL dans la barre d'adresse de votre navigateur pour le télécharger.

Download

model_urls.glb
curl -L "<model_urls.glb from the response above>" -o model.glb
Le modèle 3D résultant généré à partir de la photo d'exemple du personnage fantastique
Votre résultat

Assemblons le tout

Vous préférez un seul script qui fait tout : créer, interroger, télécharger ?

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


Prochaines étapes

  • Vous préférez une interface utilisateur ? Ouvrez la Developer Platform — exécutez des requêtes dans le Playground, suivez l'utilisation et les journaux de requêtes, et gérez les webhooks.
  • Parcourez la référence de l'API complète pour découvrir chaque point de terminaison.
  • Apprenez à partir d'exemples concrets : suivez les recettes pas à pas du Cookbook et lisez les tutoriels et récits de développement sur le Blog développeurs.
  • Consultez la Tarification, les limites de débit et les Erreurs avant de passer en production.
  • Suivez le journal des modifications pour les mises à jour et corrections de bugs.
  • Vous avez des retours ou rencontrez des problèmes ? Rejoignez notre communauté Discord — nous serions ravis de vous entendre !