3D生成

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

入力タイプの選択Copy Anchor Link

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

この endpoint では operation フィールドではなく入力タイプを使用します。モデル metadata では 3D 機能が text-to-3d や image-to-3d として示されます。3d-generation は公開リクエスト operation ではありません。

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

現在の Tripo 例には、高品質な text/image-to-3D ワークフロー向けの tripo-h3.1 と、プロダクション向け 3D アセット生成の tripo-p1.0 があります。入力タイプと出力形式の対応は Models API で確認してください。

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

3Dタスクの作成Copy Anchor Link

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": "クリーントポロジーを持つスタイライズされたローポリロボットマスコット"
  }'

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

出力フォーマットの選択肢Copy Anchor Link

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

アセットのポーリングと保存Copy Anchor Link

最初に返された poll_url を使用してください。クライアントが固定ルートを必要とする場合は、 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 を含む場合があります。ユーザーが再アクセス、バージョン履歴、または長期的なダウンロードを必要とする場合は、選択したアセットを自社製品にダウンロードまたはキャッシュしてください。

プロダクションチェックリストCopy Anchor Link

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

一般的なエラーCopy Anchor Link

APIリファレンスCopy Anchor Link