Texte au modèle 3D

POST /v3/generation/text-to-model

Générez un modèle 3D à partir d’une invite de texte.

Paramètres de la demande

En-têtes de demande

Paramètre	Tapez	Obligatoire	Par défaut	Descriptif
Content-Type	chaîne	Oui	-	`application/json`
Authorization	chaîne	Oui	-	`Bearer {api_key}`

Paramètre	Tapez	Obligatoire	Par défaut	Descriptif
prompt	chaîne	Oui	-	Invite de texte, jusqu’à 1 024 caractères
model	chaîne	Non	`tripo-v3.1`	Version modèle AI. Valeurs prises en charge : `tripo-p1`, `tripo-turbo`, `tripo-v3.1`, `tripo-v3.0`, `tripo-v2.5`, `tripo-v2.0`
negative_prompt	chaîne	Non	-	Invite négative, jusqu’à 255 caractères
model_seed	entier	Non	Aléatoire	Graine aléatoire pour la génération de géométrie
image_seed	entier	Non	Aléatoire	Graine aléatoire pour l’étape de conversion texte-image
face_limit	entier	Non	Adaptatif	Polycount maximum pour la sortie
texture	booléen	Non	`true`	Activer les cartes de texture
pbr	booléen	Non	`true`	Activez les matériaux PBR. Lorsqu’il est activé, `texture` est forcé à `true`
texture_seed	entier	Non	Aléatoire	Graine aléatoire pour la génération de texture
texture_quality	chaîne	Non	`standard`	Qualité des textures. Valeurs prises en charge : `fast` (nécessite `texture_version=v3.5-20260815`), `standard`, `detailed`, `extreme`
texture_version	chaîne	Non	Dérivé de model	Fixe le modèle de texture indépendamment de la géométrie. Valeurs prises en charge : `v3.5-20260815`, `v3.0-20250812`, `v2.5-20250123`. En cas d’omission, il est dérivé du `model` de géométrie (géométrie v2.5 → `v2.5-20250123`, sinon `v3.0-20250812`)
delight	booléen	Non	`true`	Supprime l’éclairage incrusté de l’image de référence avant le texturage. Pris en compte uniquement lorsque `texture_version=v3.5-20260815`
geometry_quality	chaîne	Non	`standard`	Qualité de la géométrie. `standard` (équilibré), `detailed` (mode Ultra)
auto_size	booléen	Non	`false`	Redimensionnez automatiquement le modèle aux dimensions réelles en mètres
quad	booléen	Non	`false`	Générez un maillage quadruple. Lorsqu’il est activé, le format de sortie est forcé à FBX
smart_low_poly	booléen	Non	`false`	Générez un modèle low-poly avec un style de topologie conçu à la main
generate_parts	booléen	Non	`false`	Générez des pièces segmentées modifiables. Non compatible avec `texture`, `pbr`, `quad` ou `smart_low_poly` — voir la note ci-dessous
compress	chaîne	Non	-	Type de compression. `geometry` (compression méshopt)
export_orientation	chaîne	Non	`+x`	Orientation export. Valeurs disponibles : `-x`, `-y`, `+y`

Remarques sur generate_parts :

Non compatible avec texture, pbr, quad ou smart_low_poly :

texture=true ou pbr=true — y compris l’omission de texture, qui vaut true par défaut — la requête est rejetée avec le code d’erreur 1004.
quad=true — quad est ignoré ; les pièces retournées sont des maillages triangulaires.
smart_low_poly=true — smart_low_poly est prioritaire et les pièces ne sont PAS produites.

Pour générer des pièces, définissez texture=false et pbr=false, et n’envoyez ni quad ni smart_low_poly.

Remarques sur export_orientation :

S’applique uniquement à cette génération. Si le modèle doit être utilisé dans des tâches de post-traitement (texture, rig, reciblage, conversion, …), il est recommandé de ne pas définir ce paramètre.
Lorsqu’il est défini, le post-traitement peut affecter le résultat final en raison d’une orientation incorrecte du modèle, tout en rapportant status: success — aucune erreur n’est levée. À utiliser avec prudence.
Si vous prévoyez de post-traiter le modèle, laissez ce paramètre vide et convertissez l’orientation à la dernière étape via /v3/models/convert.

Les paramètres suivants ne sont valides que lorsque model >= tripo-v3.0 : texture_quality, geometry_quality, auto_size, quad, smart_low_poly, generate_parts, compress.

Exemples de demande

curl -X POST https://openapi.tripo3d.ai/v3/generation/text-to-model \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "prompt": "A cat wearing a spacesuit",
    "model": "tripo-v3.1",
    "texture": true,
    "pbr": true,
    "texture_quality": "detailed"
  }'

import requests

url = "https://openapi.tripo3d.ai/v3/generation/text-to-model"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
}
payload = {
    "prompt": "A cat wearing a spacesuit",
    "model": "tripo-v3.1",
    "texture": True,
    "pbr": True,
    "texture_quality": "detailed"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

const url = "https://openapi.tripo3d.ai/v3/generation/text-to-model";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
  },
  body: JSON.stringify({
    prompt: "A cat wearing a spacesuit",
    model: "tripo-v3.1",
    texture: true,
    pbr: true,
    texture_quality: "detailed"
  })
});

const data = await response.json();
console.log(data);

Réponse

Réponse réussie

JSON

{
  "code": 0,
  "data": {
    "task_id": "task_abc123"
  }
}

Champs de réponse

Paramètre	Tapez	Descriptif
code	entier	Code d’état. `0` indique le succès
data.task_id	chaîne	Identifiant de tâche unique utilisé pour interroger la progression et les résultats de la génération

Codes d’erreur

Code d’état HTTP	Code d’erreur	Descriptif	Recommandation
429	2000	Limite de génération dépassée	Réduisez la fréquence des demandes et réessayez plus tard
400	2002	Paramètre de requête non pris en charge	Vérifier les noms des paramètres du corps de la requête et les plages de valeurs
400	2008	L’entrée viole la politique relative au contenu	Révisez l’invite et supprimez les descriptions qui ne respectent pas les règles.
403	2010	Crédits insuffisants	Ajoutez des crédits et réessayez
400	2015	Version du modèle obsolète	Mettez à niveau `model` vers une version actuellement prise en charge
400	2018	Le modèle est trop complexe pour être remaillé	Réduisez `face_limit` ou simplifiez l’invite de saisie