lowpoly sera retiré le 30 oct. 2026. meshy-7 sera retiré en tant que modèle de génération 3D le 31 déc. 2026 ; il reste disponible en tant que modèle de texture. Changez de modèle avant ces dates pour éviter les erreurs de requête. Voir toutes les dépréciations

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

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

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


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

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

Illustration d'un personnage fantastique utilisée comme entrée Image en 3D dans ce guide
Exemple d'entrée

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

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
}

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.


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

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 du personnage fantastique d'exemple
Votre résultat

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


Prochaines étapes