Умная сегментация

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 / WebP	Нет	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	строка	CDN-подпись URL семантической маски PNG.
data.output.seg_model_url	строка	CDN-подпись URL сегментированной модели GLB
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