スマートセグメンテーション

POST /v3/mesh/smartsegment

エンドツーエンドのスマートセグメンテーションパイプライン。 file_token またはパブリック URL 経由で送信します。 image と model の両方のパスをサポートします。画像パイプラインの自動モデル化とセグメント化 (85 クレジット)。モデルパイプラインは既存の GLB (55 クレジット) をセグメント化します。

/v3/mesh/segment との違い: SmartSegment は完全なパイプライン (アセット → 自動モデリング → セグメンテーション) です。 /v3/mesh/segment は 既存のモデル のみをセグメント化します。

リクエストパラメータ

リクエストヘッダー

パラメータ	種類	必須	デフォルト	説明
Content-Type	文字列	はい	—	`application/json`
Authorization	文字列	はい	—	`Bearer {api_key}`

リクエストボディ

パラメータ	種類	必須	デフォルト	説明
seg_type	文字列	はい	—	セグメンテーションタイプ: `image` (画像パイプライン、85 クレジット) / `model` (モデルパイプライン、55 クレジット)
input	文字列	はい	—	入力ソース: `file_token` (`/v3/files` または `/v3/files/presign` から) またはパブリック URL
granularity	文字列	いいえ	`medium`	セグメンテーションの粒度: `coarse` / `medium` / `fine`
hint	文字列	いいえ	—	セグメント化するパーツを特定するのに役立つオプションのヒント
transform	番号[]	条件付き	—	`seg_type=model`の場合は必須。列優先の 4×4 変換行列 (16 浮動小数点数)

seg_type と形式の制約

seg_type	入力	フォーマット	別途必要	クレジット	応答タイプ
`image`	画像 file_token または URL	PNG / JPEG / ウェブP	なし	85	`smartsegment_image`
`model`	3Dモデル file_token または URL	GLBのみ	`transform`	55	`smartsegment_model`

seg_type=model 形式制限: モデル入力 GLB (バイナリ glTF) である必要があります。 GLB 以外のファイルはパラメータエラーを返します。

transform は列優先の 4×4 行列です。共通単位行列:

JSON

[1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1]

リクエスト例

curl — 画像 (file_token)

Bash

curl -X POST https://openapi.tripo3d.ai/v3/mesh/smartsegment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "seg_type": "image",
    "input": "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "granularity": "medium",
    "hint": "game character with sword and armor"
  }'

curl — モデル (URL + 変換)

Bash

curl -X POST https://openapi.tripo3d.ai/v3/mesh/smartsegment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "seg_type": "model",
    "input": "https://example.com/character.glb",
    "transform": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1],
    "granularity": "fine",
    "hint": "character body parts"
  }'

import requests

url = "https://openapi.tripo3d.ai/v3/mesh/smartsegment"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
}
payload = {
    "seg_type": "image",
    "input": "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "granularity": "medium"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

const url = "https://openapi.tripo3d.ai/v3/mesh/smartsegment";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
  },
  body: JSON.stringify({
    seg_type: "image",
    input: "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    granularity: "medium"
  })
});

const data = await response.json();
console.log(data);

応答

成功を生み出す

JSON

{
  "code": 0,
  "data": {
    "task_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "type": "smartsegment_image",
    "status": "queued"
  }
}

タスクの結果 (成功)

標準の API GET /v3/tasks/{task_id} でポーリングします。

JSON

{
  "code": 0,
  "data": {
    "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "smartsegment_image",
    "status": "success",
    "progress": 100,
    "input": {
      "granularity": "medium"
    },
    "output": {
      "prompt": "head, body, left arm, right arm, legs",
      "mask_url": "https://cdn.tripo3d.ai/.../mask.png?auth_key=...",
      "seg_model_url": "https://cdn.tripo3d.ai/.../model.glb?auth_key=...",
      "seg_task_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "model_task_id": "d4e5f6a7-b8c9-0123-defa-456789012345"
    },
    "credits_consumed": 85.00,
    "created_at": "2026-06-30T09:08:14.882623Z",
    "completed_at": "2026-06-30T09:14:15.183547Z"
  }
}

応答フィールド

パラメータ	種類	説明
code	整数	ステータスコード。 `0` は成功を示します
data.task_id	文字列	進行状況と結果をポーリングするために使用される固有のタスク ID
data.output.prompt	文字列	自動生成されたカンマ区切りの英語ラベル
data.output.mask_url	文字列	PNG セマンティックマスクの CDN-署名済み URL
data.output.seg_model_url	文字列	CDN-セグメント化されたGLBモデルの署名付きURL
data.output.seg_task_id	文字列	内部 mesh_segmentation サブタスク ID
data.output.model_task_id	文字列	内部 image_to_model / import_model サブタスク ID

エラーコード

HTTP ステータスコード	エラーコード	説明	おすすめ
429	2000	生成の同時実行制限を超えました	リクエスト率を下げて後で再試行してください
400	1004	無効なパラメータエラー (無効な形式、GLB 以外、変換の欠落など)	`seg_type` / `input` / `transform` をチェックする
402	2001	クレジットが不十分です	クレジットをリチャージして再試行してください
401	4000	認証に失敗しました	API Keyを確認してください