テキストを 3D モデルに変換

POST /v3/generation/text-to-model

テキストプロンプトから 3D モデルを生成します。

リクエストパラメータ

リクエストヘッダー

パラメータ	種類	必須	デフォルト	説明
Content-Type	文字列	はい	-	`application/json`
Authorization	文字列	はい	-	`Bearer {api_key}`

パラメータ	種類	必須	デフォルト	説明
prompt	文字列	はい	-	テキストプロンプト、最大 1024 文字
model	文字列	いいえ	`tripo-v3.1`	AI モデルのバージョン。サポートされている値: `tripo-p1`、`tripo-turbo`、`tripo-v3.1`、`tripo-v3.0`、`tripo-v2.5`、`tripo-v2.0`
negative_prompt	文字列	いいえ	-	否定プロンプト、最大 255 文字
model_seed	整数	いいえ	ランダム	ジオメトリ生成用のランダムシード
image_seed	整数	いいえ	ランダム	テキストから画像への段階のランダムシード
face_limit	整数	いいえ	アダプティブ	出力の最大ポリ数
texture	ブール値	いいえ	`true`	テクスチャマップを有効にする
pbr	ブール値	いいえ	`true`	PBR マテリアルを有効にします。有効にすると、`texture` は強制的に `true` になります。
texture_seed	整数	いいえ	ランダム	テクスチャ生成用のランダムシード
texture_quality	文字列	いいえ	`standard`	テクスチャの品質。サポートされている値: `fast`（`texture_version=v3.5-20260815` が必要）、`standard`、`detailed`、`extreme`
texture_version	文字列	いいえ	model から導出	ジオメトリとは独立にテクスチャモデルを指定します。サポートされている値: `v3.5-20260815`、`v3.0-20250812`、`v2.5-20250123`。省略した場合はジオメトリの `model` から導出されます（v2.5 ジオメトリ → `v2.5-20250123`、それ以外 → `v3.0-20250812`）。
delight	ブール値	いいえ	`true`	テクスチャリング前に参照画像の焼き込まれた照明を除去します。`texture_version=v3.5-20260815` の場合のみ有効です。
geometry_quality	文字列	いいえ	`standard`	ジオメトリの品質。 `standard` (バランス)、`detailed` (ウルトラモード)
auto_size	ブール値	いいえ	`false`	モデルを現実世界のメートル単位の寸法に自動的にスケールします
quad	ブール値	いいえ	`false`	クワッドメッシュを出力します。有効にすると、出力形式は強制的に FBX になります。
smart_low_poly	ブール値	いいえ	`false`	手作りのトポロジスタイルでローポリモデルを生成する
generate_parts	ブール値	いいえ	`false`	編集可能なセグメント化されたパーツを生成します。`texture`、`pbr`、`quad`、`smart_low_poly` とは非互換 — 下記の注を参照
compress	文字列	いいえ	-	圧縮タイプ。 `geometry` (meshopt 圧縮)
export_orientation	文字列	いいえ	`+x`	輸出方向。使用可能な値: `-x`、`-y`、`+y`

generate_parts に関する注意:

texture、pbr、quad、smart_low_poly とは非互換です:

texture=true または pbr=true — texture を省略した場合（デフォルトは true）も含む — リクエストはエラーコード 1004 で拒否されます。
quad=true — quad は無視され、返されるパーツは三角メッシュになります。
smart_low_poly=true — smart_low_poly が優先され、パーツは生成されません。

パーツを生成するには、texture=false と pbr=false を設定し、quad と smart_low_poly を送信しないでください。

export_orientation に関する注意:

この生成にのみ適用されます。後処理タスク（テクスチャ、リグ、リターゲット、変換など）でモデルを使用する場合は、このパラメータを設定しないことをお勧めします。
設定した場合、後処理でモデルの向きが誤っているため最終結果に影響する可能性がありますが、タスクは引き続き status: success を報告します — エラーは発生しません。慎重に使用してください。
モデルを後処理する予定がある場合は、このパラメータを設定せず、最後のステップで /v3/models/convert を使って向きを変換してください。

次のパラメータは、model >= tripo-v3.0 の場合にのみ有効です: texture_quality、geometry_quality、auto_size、quad、smart_low_poly、generate_parts、compress。

リクエスト例

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

応答

成功の応答

JSON

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

応答フィールド

パラメータ	種類	説明
code	整数	ステータスコード。 `0` は成功を示します
data.task_id	文字列	生成の進行状況と結果をクエリするために使用される一意のタスク識別子

エラーコード

HTTP ステータスコード	エラーコード	説明	おすすめ
429	2000	世代制限を超えました	リクエストの頻度を減らし、後で再試行してください
400	2002	サポートされていないリクエストパラメータです	リクエストボディのパラメータ名と値の範囲を確認してください
400	2008	入力がコンテンツポリシーに違反しています	プロンプトを修正し、ポリシーに違反する説明を削除します。
403	2010	クレジットが不十分です	クレジットを追加して再試行してください
400	2015	モデルのバージョンが非推奨になりました	`model` を現在サポートされているバージョンにアップグレードします
400	2018	モデルが複雑すぎて再メッシュできません	`face_limit` を下げるか、入力プロンプトを簡素化します