Image vers modèle 3D

POST /v3/generation/image-to-model

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

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
input	chaîne	Oui	-	Source des images. Accepte un jeton de fichier commençant par `file_`, un URL commençant par `http(s)://` ou une tâche ID commençant par `task_`.
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`
enable_image_autofix	booléen	Non	`false`	Utilisé pour la complétion par IA et l’amélioration du rendu 3D. Améliorez automatiquement les images d’entrée de mauvaise qualité
texture_alignment	chaîne	Non	`original_image`	Priorité d’alignement des textures. Valeurs prises en charge : `original_image` (priorité à la correspondance avec l’image d’origine), `geometry` (priorité à la correspondance avec la géométrie)
orientation	chaîne	Non	`default`	Orientation du modèle. Valeurs prises en charge : `default`, `align_image` (aligner sur le point de vue de l’image d’entrée)
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/image-to-model \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "input": "https://example.com/image.png",
    "model": "tripo-v3.1",
    "texture": true,
    "pbr": true,
    "texture_quality": "detailed"
  }'

import requests

url = "https://openapi.tripo3d.ai/v3/generation/image-to-model"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
}
payload = {
    "input": "https://example.com/image.png",
    "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/image-to-model";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
  },
  body: JSON.stringify({
    input: "https://example.com/image.png",
    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	2003	Le fichier d’entrée est vide	Confirmez que le fichier téléchargé n’est pas vide ou que le URL est accessible
400	2004	Type de fichier non pris en charge	Utilisez un format d’image pris en charge (PNG, JPEG, WebP)
400	2008	L’entrée viole la politique relative au contenu	Remplacez l’image d’entrée et supprimez le contenu qui enfreint 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 la saisie