image_urlstring必須P1 では、10 MB 以下の JPEG、PNG、WebP で、一つの物体全体を指定します。
- デフォルト値
- 指定なし
- 制約
- minLength:1contentMediaType:["image/jpeg","image/png","image/webp","image/gif"]
例は、選択中のエンドポイントの公開パラメーター定義から作っています。API キーとサンプル素材を差し替えて、ご自身のサーバーから送信してください。
SDK・連携https://api.spicyapi.ai/api/v1/jobs/createTaskAPI キーはサーバーの環境変数 SPICY_API_KEY に保存します。Bearer 認証を使用し、JSON リクエストには Content-Type: application/json を指定してください。
Authorization: Bearer $SPICY_API_KEY# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "tripo/p1/image-to-3d",
"input": {
"generate_pbr": true,
"generate_texture": true,
"image_url": "https://example.com/reference.png",
"model_orientation": "default",
"texture_alignment": "original_image",
"texture_quality": "standard"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"このモデルの入力スキーマから生成した例です。API はどのリクエストも、同じスキーマで検証します。
これらのフィールドは、リクエスト本文の input オブジェクトに指定します。名前と型は API と一致します。デフォルト値の指定がない項目に、デフォルト値があると想定しないでください。
image_urlstring必須P1 では、10 MB 以下の JPEG、PNG、WebP で、一つの物体全体を指定します。
texture_seedinteger任意P1 では、テクスチャ段階の比較用シードです。P1 では、同じ表面が必ず得られるわけではありません。
seedinteger任意P1 では、形状段階のシードです。P1 では、一度に一設定を変える比較に使えますが、完全な再現は保証されません。
uv_unwrapboolean任意P1 では、既定で有効です。P1 では、オフにすると速く小さくなりますが、後からテクスチャを付けるための UV 座標がなくなります。
auto_sizeboolean任意P1 では、既定で無効です。P1 では、実寸を推定して調整し、テクスチャ出力を必要とします。
texture_alignmentstring任意P1 では、original_image は元画像、geometry は生成した形状に合わせてテクスチャを配置します。
"original_image""geometry"model_orientationstring任意P1 では、default は通常の向き、align_image は画像に合わせた向きにします。
"default""align_image"image_autofixboolean任意P1 では、既定で無効です。P1 では、ぼけた画像や低解像度画像を先に補正するため、処理が長くなります。
face_limitinteger任意P1 では、50~20,000 面を目標にします。P1 では、省略するとモデルが決めます。
remove_lightingboolean任意P1 では、既定で有効ですが、v3.5 のみで働きます。P1 では、参考画像に焼き付いた照明を除去します。
texture_versionstring任意P1 では、既定の v3.0-20250812 または v3.5-20260815 を選びます。P1 では、fast と照明除去には v3.5 を使います。
"v3.0-20250812""v3.5-20260815"texture_qualitystring任意料金に影響P1 では、standard が既定です。P1 では、detailed と extreme(8K)は追加料金があり、fast は v3.5 を使って standard と同額になります。P1 では、白モデルには品質の追加料金がありません。
"standard""detailed""extreme""fast"generate_pbrboolean任意料金に影響P1 では、既定で有効です。P1 では、generate_texture がオフでも PBR 材質によってテクスチャが有効になります。
generate_textureboolean任意料金に影響P1 では、既定で有効です。P1 では、色のテクスチャをなくすには generate_pbr もオフにします。
{
"additionalProperties": false,
"properties": {
"auto_size": {
"default": false,
"description": "Scale the mesh to estimated real-world dimensions. Off by default.",
"type": "boolean",
"x-ui": {
"advanced": true,
"affects_price": false,
"order": 30,
"widget": "switch"
}
},
"face_limit": {
"description": "Target face count, 50 to 20,000. Leave empty to let the model decide. Does not change the price.",
"maximum": 20000,
"minimum": 50,
"type": "integer",
"x-ui": {
"affects_price": false,
"order": 65,
"step": 50,
"widget": "slider"
}
},
"generate_pbr": {
"default": true,
"description": "Add PBR material maps (metal-roughness and normal). On by default and switches texturing on.",
"type": "boolean",
"x-ui": {
"affects_price": true,
"order": 85,
"widget": "switch"
}
},
"generate_texture": {
"default": true,
"description": "Paint a texture onto the mesh. On by default; turning it off only removes texturing if generate_pbr is off too.",
"type": "boolean",
"x-ui": {
"affects_price": true,
"order": 90,
"widget": "switch"
}
},
"image_autofix": {
"default": false,
"description": "Clean up a blurry, noisy or low-resolution picture before generation. Slower. Off by default; does not change the price.",
"type": "boolean",
"x-ui": {
"advanced": true,
"affects_price": false,
"order": 45,
"widget": "switch"
}
},
"image_url": {
"contentMediaType": [
"image/jpeg",
"image/png",
"image/webp",
"image/gif"
],
"description": "The picture to turn into a 3D model: one object or character, fully in frame. JPEG, PNG or WebP up to 10 MB.",
"minLength": 1,
"type": "string",
"x-ui": {
"accept": [
"image/jpeg",
"image/png",
"image/webp"
],
"max_size_mb": 10,
"order": 100,
"primary": true,
"widget": "upload"
}
},
"model_orientation": {
"default": "default",
"description": "default keeps the standard orientation; align_image rotates the model to match the picture.",
"enum": [
"default",
"align_image"
],
"type": "string",
"x-ui": {
"affects_price": false,
"enum_labels": {
"align_image": "Match picture",
"default": "Default"
},
"order": 40,
"widget": "radio"
}
},
"remove_lighting": {
"default": true,
"description": "Remove the lighting and shadows baked into the picture before texturing, so the texture reacts cleanly to scene lights. On by default; only takes effect with the v3.5 texture model. Does not change the price.",
"type": "boolean",
"x-ui": {
"affects_price": false,
"order": 77,
"widget": "switch"
}
},
"seed": {
"description": "Seed for the geometry step, for reproducible shapes.",
"maximum": 2147483647,
"minimum": 0,
"type": "integer",
"x-ui": {
"advanced": true,
"order": 20,
"widget": "number"
}
},
"texture_alignment": {
"default": "original_image",
"description": "Align the texture to the original picture (the default) or to the generated geometry.",
"enum": [
"original_image",
"geometry"
],
"type": "string",
"x-ui": {
"affects_price": false,
"enum_labels": {
"geometry": "Geometry",
"original_image": "Picture"
},
"order": 35,
"widget": "radio"
}
},
"texture_quality": {
"default": "standard",
"description": "Texture quality: standard (the default), detailed (higher resolution), extreme (8K) or fast (standard size, generated quicker with the v3.5 texture model). detailed and extreme cost more and only apply to textured meshes.",
"enum": [
"standard",
"detailed",
"extreme",
"fast"
],
"type": "string",
"x-ui": {
"affects_price": true,
"enum_labels": {
"detailed": "Detailed",
"extreme": "8K",
"fast": "Fast",
"standard": "Standard"
},
"order": 80,
"widget": "radio"
}
},
"texture_seed": {
"description": "Seed for the texture step. Keep seed fixed and change this to try new textures on the same shape.",
"maximum": 2147483647,
"minimum": 0,
"type": "integer",
"x-ui": {
"advanced": true,
"order": 10,
"widget": "number"
}
},
"texture_version": {
"default": "v3.0-20250812",
"description": "Texture model version: v3.0-20250812 (the default) or the newer v3.5-20260815. texture_quality fast and remove_lighting use v3.5. Does not change the price.",
"enum": [
"v3.0-20250812",
"v3.5-20260815"
],
"type": "string",
"x-ui": {
"affects_price": false,
"enum_labels": {
"v3.0-20250812": "v3.0",
"v3.5-20260815": "v3.5"
},
"order": 78,
"widget": "radio"
}
},
"uv_unwrap": {
"default": true,
"description": "Unwrap UV coordinates during generation. On by default; turning it off is faster and gives a smaller file, but the mesh then has no UVs for texturing later. Does not change the price.",
"type": "boolean",
"x-ui": {
"advanced": true,
"affects_price": false,
"order": 25,
"widget": "switch"
}
}
},
"required": [
"image_url"
],
"type": "object",
"x-pricing": {
"billingMode": "formula",
"variantFields": []
}
}HTTP 202 はタスクを受け付けたという意味で、生成が終わったという意味ではありません。返ってきた taskId を保存し、そのタスクの状態を問い合わせてください。結果を待っている間に、同じ内容でタスクを作り直さないでください。
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3
{
"code": 200,
"msg": "success",
"request_id": "req_example_create",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "queued",
"estimatedCost": "0.750000"
}
}受理レスポンスには今回の概算料金が含まれるため、アプリのタスク履歴と請求画面に同じ金額を表示できます。
curl --get "https://api.spicyapi.ai/api/v1/jobs/recordInfo" \
--data-urlencode "taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"ポーリングは約 2 秒間隔から始め、徐々に間隔を延ばします。終了状態になったら止めてください。通信が切れたときも、元の taskId で状態を確認します。作成をやり直すときは、同じ冪等キーと同じ本文をそのまま使い回してください。
import { verifyWebhook } from "@spicyapi/sdk";
// express.raw keeps the bytes we signed; express.json never matches.
app.post("/hooks/spicy", express.raw({ type: "application/json" }), (req, res) => {
const { payload } = verifyWebhook({
rawBody: req.body,
timestamp: req.header("X-Webhook-Timestamp"),
signature: req.header("X-Webhook-Signature"),
payloadVersion: Number(req.header("X-Webhook-Payload-Version")),
secret: process.env.SPICY_WEBHOOK_SECRET,
});
res.status(200).end();
void handleFinishedTask(payload);
});タスク作成時に callBackUrl を渡せば、完了したレコードが POST で届きます——ポーリングは一切不要です。配信には毎回 X-Webhook-Timestamp、X-Webhook-Signature、X-Webhook-Payload-Version が付きます。署名は taskId.timestamp.sha256(body) に対する HMAC-SHA256(base64)なので、生のバイト列で検証してください。JSON を解析して再度文字列化するとバイト列が変わり、検証は必ず失敗します。失敗した配信は再送されるため同じ taskId が二度届くことがあります。ハンドラーは冪等に。まず 2xx を返し、処理はその後で——応答が遅いと配信失敗として扱われます。
output を読むのは、state が succeeded のときだけにしてください。失敗したときは errorCode、errorMessage、request_id を手がかりに調べます。例に出ている料金や状態は、実際の請求ではありません。
{
"code": 200,
"msg": "success",
"request_id": "req_example_record",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"model": "tripo/p1/image-to-3d",
"state": "succeeded",
"output": {
"assets": [
{
"key": "tasks/2026/08/28/job_01k3m8x9q2z4v7n5p6r8s0t1w3/3f7a1c9e5b2d48f0a6c1e3d5b7f9a1c3.png",
"mime": "image/png",
"url": "https://example.r2.cloudflarestorage.com/results/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.png?X-Amz-Signature=SIGNATURE_FROM_RESPONSE",
"expiresAt": "2026-08-28T12:20:08.000Z"
}
]
},
"cost": "0.750000",
"settled": true,
"createdAt": "2026-08-28T12:00:00Z",
"completedAt": "2026-08-28T12:00:30Z"
}
}利用可能なファイルは assets[].url からそのまま開くか、ダウンロードできます。API の Authorization ヘッダーは不要です。署名付き URL は expiresAt で失効しますが、保存期間内であればタスクを再取得することで更新できます。処理中または利用できないファイルに URL はありません。署名付き URL は非公開情報として扱ってください。
アプリ、ターミナル、AI アシスタント、ビジュアルワークフローで SpicyAPI を活用。接続ガイドを選んでください。
上のコードを書く必要はありません。MCP サーバーを 1 回接続すれば、MCP に対応するエージェント(Claude Code、Codex、Cursor、Windsurf、VS Code、Gemini CLI、Cline、LibreChat)がこのモデルを名前で実行できます。シェルから 1 つのコマンドで実行することもできます。
Use tripo/p1/image-to-3d to edit ./poster.png — warmer light, cleaner background — and save the result next to it.
エージェントは公開カタログからモデルを引き、ローカルファイルを代わりにアップロードし、正確な見積もりと上限額を示して確認を待ちます。承認するまで課金は発生しません。
claude mcp add spicyapi -e SPICY_API_KEY=$SPICY_API_KEY \
-- npx --yes --package=@spicyapi/mcp spicyapi-mcp
npx skills add spicyapi-ai/spicy-skill1 行目でツールを、2 行目で Skill を渡します。Skill は使い方の取り決めです——課金の前に見積もりを取り、ローカルファイルはバイト列を貼らずにアップロードし、完成した成果物の URL を推測せずに読む。ほかのクライアントも同じサーバーをそれぞれの設定ファイルから使います。開発者向けページをご覧ください。
npx @spicyapi/cli tasks create --model tripo/p1/image-to-3d \
--input-json '{"generate_pbr":true,"generate_texture":true,"image_url":"https://example.com/reference.png","model_orientation":"default","texture_alignment":"original_image","texture_quality":"standard"}' \
--wait入力は上の例と同じ、このエンドポイント固有のスキーマに従います。--wait はタスクの完了までポーリングして結果を表示します。CI では --yes を追加すると確認を省略できます。先に SPICY_API_KEY を設定してください。API、CLI、MCP サーバーで同じキーを使えます。
npx @spicyapi/cli files upload ./poster.png
# -> spicy://uploads/01k3m8x9q2z4v7n5p6r8s0t1w3
npx @spicyapi/cli tasks create --model tripo/p1/image-to-3d \
--input-json '{"image_url":"spicy://uploads/01k3m8x9q2z4v7n5p6r8s0t1w3"}' \
--waitリクエストが受け取るのは URL であってバイト列ではありません。先にアップロードし、出力される spicy:// URI を渡してください。上のフィールド名はこのエンドポイントのスキーマから取ったものです。MCP 経由のエージェントはこの手順を代わりに済ませます——前述の一文が ./poster.png をそのまま指せるのはそのためです。公開 HTTPS で参照できるメディアならアップロードは不要です。
npx @spicyapi/cli tasks create --model tripo/p1/image-to-3d \
--input-json '{…}' --retention 1h --wait
npx @spicyapi/cli tasks get $TASK_ID # read back the retention that applied--retention は保持期間を短くするだけです——30m、1h、7d、あるいは 0 なら終了と同時に削除。実際に効くのはリクエスト・アカウント設定・プラットフォーム上限のうち最も短い値なので、指定した数値が通った前提で進めず、タスクレコードから読み戻してください。アカウントの許容より長い値を渡しても何も起きません。
ComfyUI Manager か下のコマンドで SpicyAPI ノードをインストールしたら、キャンバスで Tripo P1 · Image to 3D を検索してください。このノードにはこのページと同じオプションがあり、実行前に価格が表示されます。
cd ComfyUI/custom_nodes
git clone https://github.com/spicyapi-ai/comfyui-spicyapi埋め込みパネルはこのページと同じスキーマを参照するため、API 仕様とのずれを防げます。ドキュメント内の検索対象にする場合は、/api/embed/models/ の JSON を取得して描画してください。
<iframe src="https://spicyapi.ai/embed/ja/models/tripo-p1/api?model=tripo%2Fp1%2Fimage-to-3d" width="100%" height="560" loading="lazy" title="リクエスト例" style="border:1px solid rgba(0,0,0,.12)"></iframe>