image_urlstring必須モデル化する画像。JPEG・PNG・WebP、10 MB まで。被写体は 1 つ、全体がフレームに収まり、背景は無地。斜め 45 度の画像がいちばん奥行きの手がかりになります。
- デフォルト値
- 指定なし
- 制約
- 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/h3.1/image-to-3d",
"input": {
"generate_parts": false,
"generate_pbr": true,
"generate_texture": true,
"geometry_quality": "standard",
"image_url": "https://example.com/reference.png",
"low_poly": false
}
}'
# 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必須モデル化する画像。JPEG・PNG・WebP、10 MB まで。被写体は 1 つ、全体がフレームに収まり、背景は無地。斜め 45 度の画像がいちばん奥行きの手がかりになります。
texture_seedinteger任意テクスチャの段階の任意のシード。seed を固定してこれを変えると、同じ形に別のテクスチャを試せます。
seedinteger任意形状の段階の任意のシード。固定すると同じ形を再現できます。
uv_unwrapboolean任意既定でオン。オフにすると UV 展開を省くため、生成が速くなり、ファイルも小さくなります。ただしメッシュにはテクスチャ座標が残らず、後からテクスチャを付けられません。料金は変わりません。
auto_sizeboolean任意既定でオフ。オンにすると推定した実寸にメッシュをスケーリングし、AR や 3D プリントに便利です。料金は変わりません。
texture_alignmentstring任意original_image(既定)はテクスチャを画像に、geometry は生成された形状に合わせます。料金は変わりません。
"original_image""geometry"model_orientationstring任意default はモデル標準の向き、align_image は画像の見え方に合わせて結果を回転させます。料金は変わりません。
"default""align_image"image_autofixboolean任意既定でオフ。オンにすると、モデル化の前にぼやけた、ノイズの多い、または低解像度の画像を補正します。その分時間がかかります。料金は変わりません。
face_limitinteger任意任意の目標面数、1,000〜2,000,000。空のままだとモデル任せで 100 万面を超えることもあります。たいていの Web ビューアーには 5 万〜20 万が合います。料金は変わりません。
generate_partsboolean任意料金に影響既定でオフ。オンにすると、モデルを一つの GLB の中の名前付きパーツとして返します(おもちゃの宇宙飛行士の例では 18 パーツ)。パーツにはテクスチャがなく、常に三角形なので、テクスチャ関連のオプションと quad_mesh は無視され、課金もされません。それでも料金の合計は、テクスチャ付きの既定設定より高くなります。
low_polyboolean任意料金に影響既定でオフ。オンにすると、手作業でモデリングしたような、きれいで軽いトポロジーのメッシュを作り、単純な小物に向きます。face_limit は 20,000 以下に抑えてください。検証では、ブーツに face_limit 5,000 を指定したところ 7,675 三角面が返りました。料金に加算されます。
quad_meshboolean任意料金に影響既定でオフ。オンにすると三角形ではなく四角形ポリゴンで返り、モデリングソフトで編集しやすくなります。このときファイルは GLB ではなく FBX(テクスチャ埋め込み)になります。料金に少し加算されます。generate_parts がオンのときは無視され、課金もされません。パーツは GLB の中で三角形のままです。
geometry_qualitystring任意料金に影響standard(既定)か detailed。detailed は表面の細部をより細かく作り、いちばん高い加算オプションです。
"standard""detailed"remove_lightingboolean任意既定でオン。テクスチャを付ける前に、画像に焼き込まれたハイライトや影を取り除き、モデルが手元のシーンの照明に反応するようにします。v3.5 のテクスチャモデルのときだけ効きます。料金は変わりません。
texture_versionstring任意v3.0-20250812(既定)か、新しい v3.5-20260815。texture_quality の fast と remove_lighting は v3.5 を前提とします。料金は変わりません。
"v3.0-20250812""v3.5-20260815"texture_qualitystring任意料金に影響standard(既定)、detailed、extreme、fast のいずれか。detailed は高解像度のテクスチャ、extreme は 8K のテクスチャを作り、どちらも料金に加算されます。fast は標準サイズのまま、v3.5 のテクスチャモデルを使い、料金は standard と同じです。いずれもテクスチャなしのメッシュや generate_parts には効果がありません。
"standard""detailed""extreme""fast"generate_pbrboolean任意料金に影響既定でオン。ベースカラーに加えて PBR のマテリアルマップ(メタリック/ラフネスと法線)を作り、generate_texture がオフでもテクスチャ処理をオンにします。generate_texture と一緒にオフにすると、素の安いメッシュになります。
generate_textureboolean任意料金に影響既定でオン。メッシュにテクスチャを塗ります。オフにしてもテクスチャの加算がなくなるのは generate_pbr もオフのときだけです。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, 1,000 to 2,000,000. Leave empty to let the model decide (often over a million faces). Does not change the price.",
"maximum": 2000000,
"minimum": 1000,
"type": "integer",
"x-ui": {
"affects_price": false,
"order": 65,
"step": 1000,
"widget": "slider"
}
},
"generate_parts": {
"default": false,
"description": "Return the model split into separate, editable parts. Parts are untextured triangle meshes, so the texture options and quad_mesh are ignored and not charged. Off by default; costs more than the textured default.",
"type": "boolean",
"x-ui": {
"affects_price": true,
"order": 67,
"widget": "switch"
}
},
"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"
}
},
"geometry_quality": {
"default": "standard",
"description": "Geometry detail: standard (the default) or detailed. detailed builds finer surface detail and costs more.",
"enum": [
"standard",
"detailed"
],
"type": "string",
"x-ui": {
"affects_price": true,
"enum_labels": {
"detailed": "Detailed",
"standard": "Standard"
},
"order": 75,
"widget": "radio"
}
},
"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"
}
},
"low_poly": {
"default": false,
"description": "Build a low-poly mesh with clean, hand-modelled-style topology instead of a dense scan-like one. Best for simple objects; keep face_limit at 20,000 or below with it. Off by default; adds to the price.",
"type": "boolean",
"x-ui": {
"affects_price": true,
"order": 68,
"widget": "switch"
}
},
"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"
}
},
"quad_mesh": {
"default": false,
"description": "Return four-sided (quad) polygons instead of triangles, for editing in modelling tools; the file then comes back as FBX instead of GLB. Off by default; adds to the price. Ignored when generate_parts is on.",
"type": "boolean",
"x-ui": {
"affects_price": true,
"order": 70,
"widget": "switch"
}
},
"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/h3.1/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/h3.1/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/h3.1/image-to-3d \
--input-json '{"generate_parts":false,"generate_pbr":true,"generate_texture":true,"geometry_quality":"standard","image_url":"https://example.com/reference.png","low_poly":false}' \
--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/h3.1/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/h3.1/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 H3.1 · 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-h3-1/api?model=tripo%2Fh3.1%2Fimage-to-3d" width="100%" height="560" loading="lazy" title="リクエスト例" style="border:1px solid rgba(0,0,0,.12)"></iframe>