メディアガイド

3D generation

テキストや画像からダウンロード可能な3Dモデルを作成します

3D generationは非同期処理です。POST /v1/3d/generations はTokenLabタスクを作成します。完了したステータスのレスポンスには、model_url や(利用可能な場合)フォーマット固有のURLなど、ダウンロード可能なモデルアセットが含まれます。

ダウンロード可能な3Dモデルファイルは、30日間の自動コピーとして保持され、そのURLはTokenLabのメディア結果URLとなります。タスクレコードおよび個別に保存されたアセットは、それぞれのライフサイクルに従います。詳細はデータ保持を参照してください。

入力タイプを選択する

入力必須オプションフィールド備考
Text-to-3Dmodel, promptformat, quality, style, seed説明文から新しいアセットを生成するのに最適
Image-to-3Dmodel, 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

このページの内容