メディアガイド
3D generation
テキストや画像からダウンロード可能な3Dモデルを作成します
3D generationは非同期処理です。POST /v1/3d/generations はTokenLabタスクを作成します。完了したステータスのレスポンスには、model_url や(利用可能な場合)フォーマット固有のURLなど、ダウンロード可能なモデルアセットが含まれます。
ダウンロード可能な3Dモデルファイルは、30日間の自動コピーとして保持され、そのURLはTokenLabのメディア結果URLとなります。タスクレコードおよび個別に保存されたアセットは、それぞれのライフサイクルに従います。詳細はデータ保持を参照してください。
入力タイプを選択する
| 入力 | 必須 | オプションフィールド | 備考 |
|---|---|---|---|
| Text-to-3D | model, prompt | format, quality, style, seed | 説明文から新しいアセットを生成するのに最適 |
| Image-to-3D | model, image_url または image; モデルがリストしている場合は prompt も | format, quality, style, seed | 選択したモデルが画像入力をサポートしている場合のみ使用可能 |
operation はオプションであり、text-to-3d または image-to-3d を指定します。省略した場合、TokenLabは image または image_url が送信された場合は image-to-3d を、それ以外の場合は text-to-3d を使用します。指定する場合は、入力内容と一致している必要があります。text-to-3d を持つモデルはプロンプトを受け入れ、image-to-3d を持つモデルは画像入力を受け入れます。
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タスクを作成する
curl https://api.tokenlab.sh/v1/3d/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "tripo-h3.1",
"prompt": "A stylized low-poly robot mascot with clean topology"
}'Image-to-3Dの場合、ソースがインターネットから取得可能な場合は https URLを使用してください。インラインのbase64 image は、モデルの詳細に image がリストされているモデルでのみ使用してください。一部のモデルは image_url のみを受け入れます。
出力フォーマット
glbはWebプレビューに適しています。fbxおよびobjは、選択したモデルがサポートしている場合、DCCパイプラインで役立ちます。usdzは、モデルによって公開されている場合、Apple ARワークフローで役立ちます。qualityの値を高くすると、待ち時間とコストが増加する可能性があります。この選択肢をユーザーに提示してください。seedは、それをサポートするモデルにおいてのみ再現性に影響します。
完成したモデルを取得する
返された id または task_id を使用して GET /v1/tasks/{id} を呼び出します。
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 にフォールバックするか、そのフォーマットをサポートするモデルを選択してください |
| Image-to-3Dが拒否された | 選択したモデルがテキスト専用であるか、画像URLに到達できません | モデルの詳細を確認し、URLを検証してください |
| アセットが重複している | タイムアウト後にリトライパスがタスクを再作成しました | リトライ前にタスクの識別情報を保存してください |
APIリファレンス
| トピック | リファレンス |
|---|---|
| 3D作成 | Create 3D |
| 3Dステータス取得 | Get 3D Status |
| タスクステータス取得 | タスクステータスの取得 |
| モデル一覧 | モデル一覧の取得 |
| 請求と価格 | Billing & Pricing |