Akıllı Segmentasyon

POST /v3/mesh/smartsegment

Uçtan uca akıllı segmentasyon hattı. file_token veya herkese açık bir URL aracılığıyla gönderin. Hem görüntü hem de model yollarını destekler: görüntü hattı otomatik modelleri ve ardından segmentler (85 kredi); model hattı mevcut bir GLB’yi (55 kredi) bölümlere ayırır.

/v3/mesh/segment ile farkı: SmartSegment tam bir ardışık düzendir (varlık → otomatik modelleme → segmentasyon). /v3/mesh/segment yalnızca mevcut modeli bölümlere ayırır.

İstek Parametreleri

Başlıkları Talep Et

Parametre	Tür	Gerekli	Varsayılan	Açıklama
Content-Type	dize	Evet	—	`application/json`
Authorization	dize	Evet	—	`Bearer {api_key}`

Talep Gövdesi

Parametre	Tür	Gerekli	Varsayılan	Açıklama
seg_type	dize	Evet	—	Segmentasyon türü: `image` (görüntü hattı, 85 kredi) / `model` (model hattı, 55 kredi)
input	dize	Evet	—	Giriş kaynağı: `file_token` (`/v3/files` veya `/v3/files/presign`’den) veya genel URL
granularity	dize	Hayır	`medium`	Segmentasyon ayrıntı düzeyi: `coarse` / `medium` / `fine`
hint	dize	Hayır	—	Bölümlere ayrılacak parçaları tanımlamaya yardımcı olacak isteğe bağlı ipucu
transform	sayı[]	Koşullu	—	`seg_type=model` olduğunda gereklidir. Sütun-ana 4×4 dönüşüm matrisi (16 kayan nokta)

seg_type ve Format Kısıtlamaları

seg_type	giriş	Biçim	Ekstra gerekli	Kredi	Yanıt türü
`image`	Resim file_token veya URL	PNG / JPEG / WebP	Yok	85	`smartsegment_image`
`model`	3B model file_token veya URL	yalnızca GLB	`transform`	55	`smartsegment_model`

seg_type=model biçim sınırı: Model girişi GLB olmalıdır (ikili glTF). GLB olmayan dosyalar parametre hatası döndürür.

transform bir sütun ana 4×4 matrisidir. Ortak kimlik matrisi:

JSON

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

Örnekler İste

curl — Resim (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 — Model (URL + dönüşüm)

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);

Yanıt

Başarı Yaratın

JSON

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

Görev Sonucu (Başarılı)

Standart API GET /v3/tasks/{task_id} ile anket yapın.

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"
  }
}

Yanıt Alanları

Parametre	Tür	Açıklama
code	tamsayı	Durum kodu. `0` başarıyı gösterir
data.task_id	dize	İlerlemeyi ve sonucu yoklamak için kullanılan benzersiz görev ID
data.output.prompt	dize	Otomatik oluşturulan, virgülle ayrılmış İngilizce etiketler
data.output.mask_url	dize	PNG anlam maskesinin CDN-imzalı URL’si
data.output.seg_model_url	dize	Bölümlere ayrılmış GLB modelinin CDN- imzalı URL’si
data.output.seg_task_id	dize	Dahili mesh_segmentation alt görevi ID
data.output.model_task_id	dize	Dahili image_to_model / import_model alt görevi ID

Hata Kodları

HTTP Durum Kodu	Hata Kodu	Açıklama	Tavsiye
429	2000	Oluşturma eşzamanlılık sınırı aşıldı	İstek oranını azaltın ve daha sonra yeniden deneyin
400	1004	Geçersiz parametre hatası (geçersiz format, GLB olmayan, eksik dönüşüm vb.)	`seg_type` / `input` / `transform`’yi kontrol edin
402	2001	Yetersiz kredi	Kredileri şarj edin ve yeniden deneyin
401	4000	Kimlik doğrulama başarısız oldu	API Key’yi kontrol edin