> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 3D生成

> テキストから3Dまたは画像から3Dのタスクを作成し、完了したアセットをポーリングし、ダウンロード可能なモデルファイルを処理します。

3D生成は非同期です。 `POST /v1/3d/generations` はTokenLabタスクを作成します。完了したステータスのレスポンスは、`model_url`などのダウンロード可能なモデルアセットを返し、利用可能な場合はフォーマット特有のURLも返します。

## 入力タイプの選択

| ワークフロー   | 必須入力                                       | オプションフィールド                           | 注意事項                              |
| -------- | ------------------------------------------ | ------------------------------------ | --------------------------------- |
| テキストから3D | `model`, `prompt`                          | `format`, `quality`, `style`, `seed` | 説明から新しいアセットを生成するのに最適です            |
| 画像から3D   | `model`, `prompt`, `image` または `image_url` | `format`, `quality`, `style`, `seed` | 選択したモデルが画像入力をサポートしている場合のみ使用してください |

どのオプションを公開するか決定する前に、モデルカタログをクエリしてください：

```bash theme={null}
curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
  -H "Authorization: Bearer sk-your-api-key"
```

すべての3Dモデルが両方の入力タイプまたはすべての出力フォーマットをサポートしているとは限りません。 `image`, `image_url`, `format`, `quality`, `style`, または `seed`を送信する前に、選択したモデル契約を確認してください。

## 3Dタスクの作成

```bash theme={null}
curl https://api.tokenlab.sh/v1/3d/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tripo3d-v2.5",
    "prompt": "クリーントポロジーを持つスタイライズされたローポリロボットマスコット",
    "format": "glb",
    "quality": "standard"
  }'
```

画像から3Dの場合は、可能な限り公開の `image_url` を使用してください。クライアントが意図的にプライベートメディアを送信し、バックエンドが大きなリクエストボディに対応できる場合のみ、インライン/base64の `image` を使用してください。

## 出力フォーマットの選択肢

* `glb` は通常、ウェブプレビューのための最も安全なデフォルトです。
* `fbx` と `obj` は、選択したモデルがそれらをサポートしている場合にDCCパイプラインに役立ちます。
* `usdz` は、モデルによって公開されている場合にApple ARワークフローに役立ちます。
* 高い `quality` 値はレイテンシとコストを増加させる可能性があります。明示的なユーザー選択として公開し、隠れたデフォルトとしては扱わないでください。
* `seed` は、モデルがそれを尊重する場合にのみ再現性に役立ちます。

## アセットのポーリングと保存

最初に返された `poll_url` を使用してください。クライアントが固定ルートを必要とする場合は、 `GET /v1/tasks/{id}` を使用してください。

```bash theme={null}
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"
```

完了したタスクは `model_url` を返し、`glb_url`, `fbx_url`, `obj_url`, または `usdz_url` を含む場合があります。ユーザーが再アクセス、バージョン履歴、または長期的なダウンロードを必要とする場合は、選択したアセットを自社製品にダウンロードまたはキャッシュしてください。

## プロダクションチェックリスト

* `task_id`, `poll_url`, モデル, リクエストされたフォーマット、および自社のアセットレコードIDを保持してください。
* ページをリフレッシュした後は、重複タスクを作成するのではなく、ポーリングを再開してください。
* タスクを作成する前に、ソース画像のサイズと到達可能性を検証してください。
* ユーザーがアセットにアクセスする権限を持っていない限り、生成されたアセットのURLを公開ページに出さないでください。
* 後の調整のために、存在する場合は `billing_transaction_id` を記録してください。

## 一般的なエラー

| 症状                 | 考えられる原因                      | 修正                                            |
| ------------------ | ---------------------------- | --------------------------------------------- |
| 作成レスポンスにアセットURLがない | 3D生成は非同期                     | 終端ステータスになるまでポーリング                             |
| リクエストされたフォーマットが欠落  | モデルがそのフォーマットを返さなかった          | `model_url` にフォールバックするか、そのフォーマットをサポートするモデルを選択 |
| 画像から3Dが拒否された       | 選択したモデルがテキスト専用または画像URLが到達不可能 | モデル契約を確認し、URLを検証                              |
| 重複アセット             | リトライパスがタイムアウト後にタスクを再作成       | リトライする前にタスクの識別情報を保存                           |

## APIリファレンス

| トピック        | リファレンス                                                 |
| ----------- | ------------------------------------------------------ |
| 3Dの作成       | [3Dの作成](/ja/api-reference/3d/create-3d)                |
| 3Dステータスの取得  | [3Dステータスの取得](/ja/api-reference/3d/get-3d-status)       |
| タスクステータスの取得 | [タスクステータスの取得](/ja/api-reference/tasks/get-task-status) |
| モデルの一覧      | [モデルの一覧](/ja/api-reference/models/list-models)         |
| 請求と価格設定     | [請求と価格設定](/ja/guides/billing)                          |