画像から 3D モデルへ

POST /v3/generation/image-to-model

画像から3Dモデルを生成します。

リクエストパラメータ

リクエストヘッダー

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

パラメータ	種類	必須	デフォルト	説明
input	文字列	はい	-	画像ソース。 `file_` で始まるファイルトークン、`http(s)://` で始まる URL、または `task_` で始まるタスク ID を受け入れます。
model	文字列	いいえ	`tripo-v3.1`	AI モデルのバージョン。サポートされている値: `tripo-p1`、`tripo-turbo`、`tripo-v3.1`、`tripo-v3.0`、`tripo-v2.5`、`tripo-v2.0`
enable_image_autofix	ブール値	いいえ	`false`	AI 補完と 3D 効果の向上に使用されます。低品質の入力画像を自動的に改善します
texture_alignment	文字列	いいえ	`original_image`	テクスチャの配置を優先します。サポートされている値: `original_image` (元のイメージとの一致を優先)、`geometry` (ジオメトリとの一致を優先)
orientation	文字列	いいえ	`default`	モデルの向き。サポートされている値: `default`、`align_image` (入力画像の視点に位置合わせ)
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/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);

応答

成功の応答

JSON

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

応答フィールド

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

エラーコード

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