Démarrage rapide
Commencez par créer votre clé API
Chaque requête de ce guide en a besoin. Créer une clé ne prend que quelques secondes.
Créez votre clé APICré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.
Vous utilisez un assistant de codage IA ? Pour connecter Claude Code, Cursor, Windsurf ou un autre client MCP à Meshy, consultez Intégration IA. Pour un agent conversationnel sans prise en charge MCP, utilisez llms.txt.
1Obtenez votre clé API
Créez une clé API sur la page API Keys de la Developer Platform. Vous ne pouvez plus revoir la clé une fois que vous quittez cet écran, alors conservez-la 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 pour les tests.

Gardez la clé en dehors de vos scripts. Stockez-la plutôt dans une variable d'environnement, comme le montre l'étape suivante.
2Créer une tâche Image en 3D
Envoyez une image à Image en 3D. Pour partir d'un prompt texte ou de plusieurs photos à la place, utilisez Texte en 3D ou Multi-image en 3D.
Tout d'abord, stockez votre clé dans une variable d'environnement :
Export your key
export MESHY_API_KEY="<your-api-key>"
Exécutez cette commande dans votre terminal (Terminal sur macOS, Invite de commandes ou PowerShell sur Windows), pas dans un navigateur.
Les exemples suivants utilisent tous cette photo. Pour essayer une autre image, modifiez 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"
}'
3Vérifier l'état 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 durées de traitement habituelles, et combien de temps attendre avant d'abandonner, consultez Cycle de vie d'une tâche.
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
}
Si la tâche échoue, status vaut FAILED, et task_error en indique la raison. Corrigez l'entrée ou créez une autre tâche. Voir Erreurs.
Pour être notifié à la fin de la tâche au lieu de l'interroger, diffusez la tâche en continu ou utilisez un webhook.
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.
Download
curl -L "<model_urls.glb from the response above>" -o model.glb

Sur tous les plans sauf Enterprise, Meshy conserve les fichiers pendant 3 jours. Téléchargez les fichiers dont vous avez besoin avant cette échéance. Voir Conservation des ressources.
Tout assembler
Ce script crée la tâche, attend sa fin, puis télécharge le modèle.
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');
Explorer les flux de travail courants
Personnage prêt pour le jeu
Riggez un maillage humanoïde avec un squelette pour qu'il soit prêt à être animé dans Unity ou Unreal.
Learn more →Maillage Smart Topology
Définissez model_type sur smart-topology pour Image en 3D afin d'obtenir un maillage triangulaire propre et prêt pour le jeu.
Modèle pour impression 3D
Convertissez un modèle terminé en un fichier 3MF multicolore, prêt à être tranché et imprimé.
Learn more →Prochaines étapes
- Parcourez chaque point 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.