Bild zum 3D-Modell

POST /v3/generation/image-to-model

Generieren Sie ein 3D-Modell aus einem Bild.

Anforderungsparameter

Anforderungsheader

Parameter	Typ	Erforderlich	Standard	Beschreibung
Content-Type	Zeichenfolge	Ja	-	`application/json`
Authorization	Zeichenfolge	Ja	-	`Bearer {api_key}`

Parameter	Typ	Erforderlich	Standard	Beschreibung
input	Zeichenfolge	Ja	-	Bildquelle. Akzeptiert ein Dateitoken, das mit `file_` beginnt, ein URL, das mit `http(s)://` beginnt, oder eine Aufgabe ID, die mit `task_` beginnt
model	Zeichenfolge	Nein	`tripo-v3.1`	Modellversion AI. Unterstützte Werte: `tripo-p1`, `tripo-turbo`, `tripo-v3.1`, `tripo-v3.0`, `tripo-v2.5`, `tripo-v2.0`
enable_image_autofix	Boolescher Wert	Nein	`false`	Für KI-Vervollständigung und verbesserte 3D-Ergebnisse. Verbessern Sie automatisch Eingabebilder mit geringer Qualität
texture_alignment	Zeichenfolge	Nein	`original_image`	Priorität der Texturausrichtung. Unterstützte Werte: `original_image` (Übereinstimmung mit dem Originalbild priorisieren), `geometry` (Übereinstimmung mit der Geometrie priorisieren)
orientation	Zeichenfolge	Nein	`default`	Modellorientierung. Unterstützte Werte: `default`, `align_image` (ausrichten am Blickwinkel des Eingabebilds)
face_limit	ganze Zahl	Nein	Adaptiv	Maximale Polyanzahl für die Ausgabe
texture	Boolescher Wert	Nein	`true`	Aktivieren Sie Texturkarten
pbr	Boolescher Wert	Nein	`true`	Aktivieren Sie PBR-Materialien. Wenn aktiviert, wird `texture` zu `true` gezwungen
texture_seed	ganze Zahl	Nein	Zufällig	Zufälliger Startwert für die Texturgenerierung
texture_quality	Zeichenfolge	Nein	`standard`	Texturqualität. Unterstützte Werte: `fast` (erfordert `texture_version=v3.5-20260815`), `standard`, `detailed`, `extreme`
texture_version	Zeichenfolge	Nein	Aus model abgeleitet	Legt das Texturmodell unabhängig von der Geometrie fest. Unterstützte Werte: `v3.5-20260815`, `v3.0-20250812`, `v2.5-20250123`. Ohne Angabe wird es aus dem Geometrie-`model` abgeleitet (v2.5-Geometrie → `v2.5-20250123`, sonst `v3.0-20250812`)
delight	Boolescher Wert	Nein	`true`	Entfernt eingebackenes Licht aus dem Referenzbild vor dem Texturieren. Wird nur bei `texture_version=v3.5-20260815` berücksichtigt
geometry_quality	Zeichenfolge	Nein	`standard`	Geometriequalität. `standard` (symmetrisch), `detailed` (Ultra-Modus)
auto_size	Boolescher Wert	Nein	`false`	Skalieren Sie das Modell automatisch auf reale Abmessungen in Metern
quad	Boolescher Wert	Nein	`false`	Geben Sie ein Quad-Netz aus. Wenn diese Option aktiviert ist, wird das Ausgabeformat auf FBX erzwungen
smart_low_poly	Boolescher Wert	Nein	`false`	Generieren Sie ein Low-Poly-Modell mit handgefertigtem Topologiestil
generate_parts	Boolescher Wert	Nein	`false`	Generieren Sie bearbeitbare segmentierte Teile. Nicht kompatibel mit `texture`, `pbr`, `quad` oder `smart_low_poly` — siehe Hinweis unten
compress	Zeichenfolge	Nein	-	Komprimierungstyp. `geometry` (Meshopt-Komprimierung)
export_orientation	Zeichenfolge	Nein	`+x`	Exportausrichtung. Verfügbare Werte: `-x`, `-y`, `+y`

Hinweise zu generate_parts:

Nicht kompatibel mit texture, pbr, quad oder smart_low_poly:

texture=true oder pbr=true — einschließlich des Weglassens von texture, das standardmäßig true ist — wird die Anfrage mit Fehlercode 1004 abgelehnt.
quad=true — quad wird ignoriert; die zurückgegebenen Teile sind Dreiecksmeshes.
smart_low_poly=true — smart_low_poly hat Vorrang und Teile werden NICHT erzeugt.

Um Teile zu generieren, setzen Sie texture=false und pbr=false und senden Sie weder quad noch smart_low_poly.

Hinweise zu export_orientation:

Gilt nur für diese Generierung. Wenn das Modell in Nachbearbeitungsaufgaben (Texturen, Rigging, Retargeting, Konvertierung, …) verwendet werden soll, wird empfohlen, diesen Parameter nicht zu setzen.
Wenn dieser Parameter gesetzt ist, kann die Nachbearbeitung aufgrund einer falschen Modellausrichtung das Endergebnis beeinträchtigen, während die Aufgabe weiterhin status: success meldet — es wird kein Fehler ausgelöst. Bitte mit Vorsicht verwenden.
Wenn Sie das Modell nachbearbeiten möchten, lassen Sie diesen Parameter leer und konvertieren Sie die Ausrichtung im letzten Schritt über /v3/models/convert.

Die folgenden Parameter sind nur gültig, wenn model >= tripo-v3.0: texture_quality, geometry_quality, auto_size, quad, smart_low_poly, generate_parts, compress.

Fordern Sie Beispiele an

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

Antwort

Erfolgsantwort

JSON

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

Antwortfelder

Parameter	Typ	Beschreibung
code	ganze Zahl	Statuscode. `0` zeigt Erfolg an
data.task_id	Zeichenfolge	Eindeutiger Aufgabenbezeichner, der zum Abfragen des Generierungsfortschritts und der Ergebnisse verwendet wird

Fehlercodes

HTTP Statuscode	Fehlercode	Beschreibung	Empfehlung
429	2000	Generationslimit überschritten	Reduzieren Sie die Anforderungshäufigkeit und versuchen Sie es später noch einmal
400	2002	Nicht unterstützter Anforderungsparameter	Überprüfen Sie die Parameternamen und Wertebereiche des Anforderungshauptteils
400	2003	Die Eingabedatei ist leer	Stellen Sie sicher, dass die hochgeladene Datei nicht leer ist oder dass auf URL zugegriffen werden kann
400	2004	Nicht unterstützter Dateityp	Verwenden Sie ein unterstütztes Bildformat (PNG, JPEG, WebP).
400	2008	Die Eingabe verstößt gegen die Inhaltsrichtlinien	Ersetzen Sie das Eingabebild und entfernen Sie richtlinienverletzende Inhalte
403	2010	Unzureichende Credits	Fügen Sie Credits hinzu und versuchen Sie es erneut
400	2015	Modellversion veraltet	Aktualisieren Sie `model` auf eine aktuell unterstützte Version
400	2018	Das Modell ist zu komplex für eine Neuvernetzung	Senken Sie `face_limit` oder vereinfachen Sie die Eingabe