SAM 3D API

SAM 3D API

SAM 3D восстанавливает объём по одной обычной фотографии и отдаёт готовую 3D-сцену в формате GLB. Нейросеть умеет две разные вещи, и режим выбирается полем sam3_generation_type:

• body - 3D-фигура человека: поза и пропорции всех людей в кадре. Подходит для референсов позы, аватаров, заготовок под риггинг и примерки;
• objects - 3D-модель выбранного предмета из кадра: кресла, игрушки, машины, статуэтки. Предмет находится по короткому названию в prompt или по готовым маскам.

Запуск стоит 4 ₽ в любом режиме. Каждый вызов создаёт асинхронную операцию: сначала приходит её id, готовый файл забирается отдельным запросом. Обычно результат готов за 10-70 секунд.

Создание операции

• Endpoint: POST /api/v1/operations
• Авторизация: Authorization: Bearer brth_...
• Выполнение асинхронное: запрос создаёт операцию и сразу возвращает её id и статус queued. Результат забирается по id.

Сценарии:

1. Фигура человека по фото (body).
2. Фигура человека с маской, когда в кадре несколько людей, а нужен один (body + mask_url).
3. Предмет по названию (objects + prompt).
4. Предметы по маскам (objects + mask_urls).

Тело запроса

{
  "tool": "sam-3d",
  "input": {
    "sam3_generation_type": "body",
    "image_url": "https://cdn.example.com/person-full-height-1.jpg",
    "use_body_mask": false,
    "export_meshes": true,
    "include_3d_keypoints": true
  }
}

• tool - slug нейросети, всегда "sam-3d".
• input - параметры запуска. Поля передаются прямо внутри input, без дополнительной вложенности.
• Набор полей зависит от режима: для body нужны поля фигуры, для objects - prompt и при желании маски.

Параметры

Поля другого режима можно не передавать: если они есть в запросе, модель их не использует.

Примеры запросов

Фигура человека по фото

Самый частый сценарий: фото человека в полный рост или по пояс. Если в кадре несколько людей, в одну сцену попадут все.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "sam-3d",
  "input": {
    "sam3_generation_type": "body",
    "image_url": "https://cdn.example.com/person-full-height-1.jpg",
    "use_body_mask": false,
    "export_meshes": true,
    "include_3d_keypoints": true
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'sam-3d',
    input: {
      sam3_generation_type: 'body',
      image_url: 'https://cdn.example.com/person-full-height-1.jpg',
      use_body_mask: false,
      export_meshes: true,
      include_3d_keypoints: true,
    },
  }),
})

const data = await response.json()
console.log(data.id, data.status)

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'sam-3d',
        'input': {
            'sam3_generation_type': 'body',
            'image_url': 'https://cdn.example.com/person-full-height-1.jpg',
            'use_body_mask': False,
            'export_meshes': True,
            'include_3d_keypoints': True,
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Один человек по маске

Если в кадре толпа, а нужна фигура одного человека, закрасьте его белым на чёрной PNG-маске того же размера и включите use_body_mask.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "sam-3d",
  "input": {
    "sam3_generation_type": "body",
    "image_url": "https://cdn.example.com/group-photo-1.jpg",
    "use_body_mask": true,
    "mask_url": "https://cdn.example.com/group-photo-1-person-mask.png",
    "export_meshes": false,
    "include_3d_keypoints": false
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'sam-3d',
    input: {
      sam3_generation_type: 'body',
      image_url: 'https://cdn.example.com/group-photo-1.jpg',
      use_body_mask: true,
      mask_url: 'https://cdn.example.com/group-photo-1-person-mask.png',
      export_meshes: false,
      include_3d_keypoints: false,
    },
  }),
})

const data = await response.json()
console.log(data.id, data.status)

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'sam-3d',
        'input': {
            'sam3_generation_type': 'body',
            'image_url': 'https://cdn.example.com/group-photo-1.jpg',
            'use_body_mask': True,
            'mask_url': 'https://cdn.example.com/group-photo-1-person-mask.png',
            'export_meshes': False,
            'include_3d_keypoints': False,
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Предмет по названию

Модель сама найдёт предмет по prompt и построит его в 3D. Пишите одно-два слова - название того, что действительно видно на фото.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "sam-3d",
  "input": {
    "sam3_generation_type": "objects",
    "image_url": "https://cdn.example.com/living-room-1.jpg",
    "prompt": "armchair",
    "detection_threshold": 0.3,
    "seed": 42,
    "export_textured_glb": true
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'sam-3d',
    input: {
      sam3_generation_type: 'objects',
      image_url: 'https://cdn.example.com/living-room-1.jpg',
      prompt: 'armchair',
      detection_threshold: 0.3,
      seed: 42,
      export_textured_glb: true,
    },
  }),
})

const data = await response.json()
console.log(data.id, data.status)

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'sam-3d',
        'input': {
            'sam3_generation_type': 'objects',
            'image_url': 'https://cdn.example.com/living-room-1.jpg',
            'prompt': 'armchair',
            'detection_threshold': 0.3,
            'seed': 42,
            'export_textured_glb': True,
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Предметы по маскам

Когда предмет не находится по названию или нужно несколько конкретных предметов, передайте маски - по одной на предмет. Все предметы окажутся в одной сцене.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "sam-3d",
  "input": {
    "sam3_generation_type": "objects",
    "image_url": "https://cdn.example.com/desk-photo-1.jpg",
    "prompt": "lamp",
    "mask_urls": [
      "https://cdn.example.com/desk-photo-1-lamp-mask.png",
      "https://cdn.example.com/desk-photo-1-mug-mask.png"
    ],
    "export_textured_glb": true
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'sam-3d',
    input: {
      sam3_generation_type: 'objects',
      image_url: 'https://cdn.example.com/desk-photo-1.jpg',
      prompt: 'lamp',
      mask_urls: [
        'https://cdn.example.com/desk-photo-1-lamp-mask.png',
        'https://cdn.example.com/desk-photo-1-mug-mask.png',
      ],
      export_textured_glb: true,
    },
  }),
})

const data = await response.json()
console.log(data.id, data.status)

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'sam-3d',
        'input': {
            'sam3_generation_type': 'objects',
            'image_url': 'https://cdn.example.com/desk-photo-1.jpg',
            'prompt': 'lamp',
            'mask_urls': [
                'https://cdn.example.com/desk-photo-1-lamp-mask.png',
                'https://cdn.example.com/desk-photo-1-mug-mask.png',
            ],
            'export_textured_glb': True,
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Примеры ответов

Ответ после создания

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "sam-3d",
  "cost": 4,
  "balance_after": 496,
  "created_at": "2026-09-30T21:31:26.036498+00:00"
}

Ответ после завершения

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "sam-3d",
  "cost": 4,
  "created_at": "2026-09-30T21:31:26.036498+00:00",
  "completed_at": "2026-09-30T21:31:49.648659+00:00",
  "result": {
    "type": "file",
    "files": [
      {
        "url": "https://storage.bratuha.ru/results/sam-3d/person-full-height-1.glb",
        "name": "result"
      }
    ]
  },
  "error_message": null
}

Ответ при ошибке

Если модель не нашла на фото то, что нужно построить, операция завершается статусом failed, result равен null, а причина лежит в error_message:

{
  "id": "op_uuid-123",
  "status": "failed",
  "tool": "sam-3d",
  "cost": 4,
  "created_at": "2026-09-30T21:31:26.036498+00:00",
  "completed_at": "2026-09-30T21:31:33.102114+00:00",
  "result": null,
  "error_message": "На изображении не обнаружено людей."
}

Для режима objects похожая ошибка звучит так: «Автоматическое выделение объектов не сработало. Попробуйте изменить запрос, добавить ссылки на маски или снизить порог обнаружения.»

Проверка статуса

Сохраните id из ответа на создание и проверяйте операцию по нему:

GET /api/v1/operations/{id}

curl -H "Authorization: Bearer brth_ваш_ключ" \
  https://bratuha.ru/api/v1/operations/op_uuid-123

async function waitForModel(id) {
  while (true) {
    const res = await fetch(`https://bratuha.ru/api/v1/operations/${id}`, {
      headers: { Authorization: 'Bearer brth_ваш_ключ' },
    })
    const op = await res.json()
    if (op.status === 'completed') return op.result.files[0].url
    if (op.status === 'failed') throw new Error(op.error_message)
    await new Promise((r) => setTimeout(r, 5000))
  }
}

Статус одной операции можно запрашивать не чаще раза в секунду, иначе придёт 429 rate_limit_exceeded. Для этой нейросети хватает опроса раз в 5 секунд.

Формат результата

После завершения в result приходит один файл - 3D-сцена в формате GLB:

{
  "type": "file",
  "files": [
    {
      "url": "https://storage.bratuha.ru/results/sam-3d/person-full-height-1.glb",
      "name": "result"
    }
  ]
}

• type - всегда "file".
• files - массив из одного элемента. url - ссылка на .glb, name - служебное имя "result", расширение берите из ссылки.
• В режиме body в GLB лежат фигуры всех найденных людей: каждый человек - отдельный узел person_00, person_01 и так далее. Фигуры без текстуры, окрашены по вершинам. При include_3d_keypoints: true рядом появляются маркеры суставов keypoint_p00_k00, keypoint_p00_k01... по 70 на человека. Файл на двух людей весит около 2 МБ.
• В режиме objects в GLB лежат найденные предметы, с текстурой при export_textured_glb: true.

GLB открывается в Blender, Windows 3D Viewer, онлайн-просмотрщиках и движках вроде Unity и Unreal. Скачайте файл к себе после завершения операции, если он нужен надолго.

Ценообразование

Цена фиксированная - 4 ₽ за запуск.

Сумма списывается при создании операции и приходит в поле cost, остаток баланса - в balance_after. Если операция завершилась ошибкой, деньги возвращаются на баланс, а cost в ответе остаётся суммой запуска.

Ограничения и практические заметки

• POST /api/v1/operations не идемпотентен: каждый запрос создаёт новую операцию и списывает деньги. Если ответ не дошёл из-за обрыва сети, не повторяйте запрос автоматически - сначала проверьте баланс или историю в аккаунте.
• Операция выполняется асинхронно: сначала приходит queued, дальше статус проверяется по id. Фигура человека обычно готова за 10-30 секунд, предмет с текстурой - до минуты с небольшим.
• Файлы передаются только внешними ссылками http/https. Адреса localhost, loopback и частные IP не принимаются. Ссылка должна открываться без авторизации и cookies, файл - до 128 МБ.
• Расширение в ссылке должно быть допустимым для поля, иначе API сразу вернёт 400 validation_error и деньги не спишутся. Для mask_url подходит только .png.
• Режим body работает только с людьми. На фото без человека, на иконках, логотипах, рисунках предметов операция завершится ошибкой «На изображении не обнаружено людей.» Чтобы построить предмет, используйте objects.
• В режиме objects чаще всего ошибаются с prompt. Пишите название предмета, который точно есть в кадре: запрос car на фото кресла не сработает. Короткие английские названия находятся надёжнее: на одном и том же фото fox сработал, а лиса - нет. Длинные описания вроде «здание зелёное» тоже не подходят.
• Если предмет не нашёлся, попробуйте по очереди: другое короткое название, detection_threshold пониже (например, 0.2), маску предмета в mask_urls.
• Лучший исходник - чёткое фото, где предмет или человек целиком в кадре и не перекрыт другими объектами. Обрезанные края достраиваются хуже.
• API не сравнивает размеры маски и фото, это нужно проверять на своей стороне до отправки.