Hi3D V3.0 API

Создаёт 3D-модель по одной картинке или по нескольким ракурсам объекта. Цена зависит от качества: 2048³ Качество - 300 ₽ за модель, 2048³ Максимум - 1300 ₽ за модель.

Нейросеть

Hi3D V3.0 API — Братуха.ру

API документация

Общая документация Public API · API-ключ можно создать в настройках аккаунта

Hi3D V3.0 API

Hi3D V3.0 строит готовую 3D-модель по фотографиям предмета: по одному снимку или по нескольким ракурсам (спереди, сзади, слева, справа). На выходе - файл модели в нужном формате: GLB или USDZ для сайта и AR, OBJ или FBX для 3D-редакторов и игровых движков, STL для 3D-печати. Модель подходит для карточек товаров, игрушек и фигурок, персонажей и предметов интерьера.

Главное, что влияет на результат: сколько ракурсов вы дадите, какое качество выберете и нужны ли текстуры. Если модель нужна только для печати, текстуры можно выключить.

Каждый вызов создаёт асинхронную операцию, и она идёт долго - обычно больше 10 минут. После запуска проверяйте статус по id.

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

Endpoint: POST /api/v1/operations
Авторизация: Authorization: Bearer brth_...
Выполнение асинхронное: запрос сразу возвращает id и стартовый статус операции.

Сценарий задаёт параметр generation_type:

image - 3D по одному изображению, ссылка в image_url.
multiview - 3D по нескольким ракурсам: обязательный вид спереди front_image_url и до трёх дополнительных видов.

Тело запроса

{
  "tool": "hi3d-v3-0",
  "input": {
    "generation_type": "image",
    "image_url": "https://cdn.example.com/toy-front.jpg",
    "resolution": "2048quality",
    "export_format": "glb"
  }
}

tool - slug нейросети, всегда "hi3d-v3-0".
input - параметры запуска. Поля передаются напрямую внутри этого объекта, без дополнительной вложенности.
Набор полей с картинками зависит от generation_type: в режиме image нужен только image_url, в режиме multiview - front_image_url и при желании остальные виды.

Параметры

Параметр	Тип	Обязательный	Описание
`generation_type`	`enum`	Да	Сценарий. `image` - одно изображение, `multiview` - несколько ракурсов. Если не передать, используется `image`.
`image_url`	`string (url)`	В режиме `image`	Фото предмета. Одна ссылка, внешний `http/https` URL с расширением `.jpg`, `.jpeg`, `.png` или `.webp`, файл до 20 МБ. Используется только при `generation_type: "image"`.
`front_image_url`	`string (url)`	В режиме `multiview`	Вид спереди - главный ракурс. Те же требования к ссылке и файлу. Используется только при `generation_type: "multiview"`.
`back_image_url`	`string (url)`	Нет	Вид сзади. Только в режиме `multiview`.
`left_image_url`	`string (url)`	Нет	Вид слева. Только в режиме `multiview`.
`right_image_url`	`string (url)`	Нет	Вид справа. Только в режиме `multiview`.
`resolution`	`enum`	Да	Качество модели. `2048quality` - «Качество», 300 ₽; `2048master` - «Максимум», больше деталей, 1300 ₽. Если не передать, используется `2048quality`.
`enable_texture`	`boolean`	Нет	Текстуры. `true` - цветная модель, `false` - только геометрия без цвета (удобно для печати). По умолчанию `true`.
`enable_pbr`	`boolean`	Нет	PBR-материалы - дополнительные карты материала (металличность, шероховатость и т.п.) для реалистичного освещения в движках. Работает только при `enable_texture: true`; без текстур всегда выключено. По умолчанию .

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

Число полигонов передаётся в двух разных полях, по одному на каждое качество. Сервер берёт то, которое соответствует выбранному resolution, второе игнорирует.

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

3D по одному изображению

Базовый сценарий: одно фото предмета, модель с текстурами и PBR-материалами в GLB.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "hi3d-v3-0",
  "input": {
    "generation_type": "image",
    "image_url": "https://cdn.example.com/toy-front.jpg",
    "resolution": "2048quality",
    "enable_texture": true,
    "enable_pbr": true,
    "face_count_quality": 2000000,
    "export_format": "glb",
    "enable_safety_checker": true,
    "shading": 0.5
  }
}'

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: 'hi3d-v3-0',
    input: {
      generation_type: 'image',
      image_url: 'https://cdn.example.com/toy-front.jpg',
      resolution: '2048quality',
      enable_texture: true,
      enable_pbr: true,
      face_count_quality: 2000000,
      export_format: 'glb',
      enable_safety_checker: true,
      shading: 0.5,
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'hi3d-v3-0',
        'input': {
            'generation_type': 'image',
            'image_url': 'https://cdn.example.com/toy-front.jpg',
            'resolution': '2048quality',
            'enable_texture': True,
            'enable_pbr': True,
            'face_count_quality': 2000000,
            'export_format': 'glb',
            'enable_safety_checker': True,
            'shading': 0.5,
        },
    },
    timeout=30,
)

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

3D по нескольким ракурсам

Четыре вида одного предмета дают более точную форму со всех сторон, особенно сзади, где по одному фото модели приходится догадываться. Здесь модель без PBR-материалов, 1 млн полигонов, формат FBX.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "hi3d-v3-0",
  "input": {
    "generation_type": "multiview",
    "front_image_url": "https://cdn.example.com/toy-front.jpg",
    "back_image_url": "https://cdn.example.com/toy-back.jpg",
    "left_image_url": "https://cdn.example.com/toy-left.jpg",
    "right_image_url": "https://cdn.example.com/toy-right.jpg",
    "resolution": "2048quality",
    "enable_texture": true,
    "enable_pbr": false,
    "face_count_quality": 1000000,
    "export_format": "fbx",
    "shading": 0.5
  }
}'

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: 'hi3d-v3-0',
    input: {
      generation_type: 'multiview',
      front_image_url: 'https://cdn.example.com/toy-front.jpg',
      back_image_url: 'https://cdn.example.com/toy-back.jpg',
      left_image_url: 'https://cdn.example.com/toy-left.jpg',
      right_image_url: 'https://cdn.example.com/toy-right.jpg',
      resolution: '2048quality',
      enable_texture: true,
      enable_pbr: false,
      face_count_quality: 1000000,
      export_format: 'fbx',
      shading: 0.5,
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'hi3d-v3-0',
        'input': {
            'generation_type': 'multiview',
            'front_image_url': 'https://cdn.example.com/toy-front.jpg',
            'back_image_url': 'https://cdn.example.com/toy-back.jpg',
            'left_image_url': 'https://cdn.example.com/toy-left.jpg',
            'right_image_url': 'https://cdn.example.com/toy-right.jpg',
            'resolution': '2048quality',
            'enable_texture': True,
            'enable_pbr': False,
            'face_count_quality': 1000000,
            'export_format': 'fbx',
            'shading': 0.5,
        },
    },
    timeout=30,
)

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

Модель для 3D-печати

Максимальное качество, без текстур, файл STL. Достаточно вида спереди и сзади: боковые виды необязательны.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "hi3d-v3-0",
  "input": {
    "generation_type": "multiview",
    "front_image_url": "https://cdn.example.com/figure-front.png",
    "back_image_url": "https://cdn.example.com/figure-back.png",
    "resolution": "2048master",
    "enable_texture": false,
    "face_count_master": 5000000,
    "export_format": "stl",
    "shading": 0.5
  }
}'

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: 'hi3d-v3-0',
    input: {
      generation_type: 'multiview',
      front_image_url: 'https://cdn.example.com/figure-front.png',
      back_image_url: 'https://cdn.example.com/figure-back.png',
      resolution: '2048master',
      enable_texture: false,
      face_count_master: 5000000,
      export_format: 'stl',
      shading: 0.5,
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'hi3d-v3-0',
        'input': {
            'generation_type': 'multiview',
            'front_image_url': 'https://cdn.example.com/figure-front.png',
            'back_image_url': 'https://cdn.example.com/figure-back.png',
            'resolution': '2048master',
            'enable_texture': False,
            'face_count_master': 5000000,
            'export_format': 'stl',
            'shading': 0.5,
        },
    },
    timeout=30,
)

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

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

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

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "hi3d-v3-0",
  "cost": 300,
  "balance_after": 700,
  "created_at": "2026-10-01T12:00:00Z"
}

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

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "hi3d-v3-0",
  "cost": 300,
  "created_at": "2026-10-01T12:00:00Z",
  "completed_at": "2026-10-01T12:12:34Z",
  "result": {
    "type": "file",
    "files": [
      {
        "url": "https://storage.bratuha.ru/results/hi3d-v3-0/model.glb",
        "name": "result"
      }
    ]
  },
  "error_message": null
}

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

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

GET /api/v1/operations/{id}

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

const res = await fetch('https://bratuha.ru/api/v1/operations/op_uuid-123', {
  headers: { Authorization: 'Bearer brth_ваш_ключ' },
})
const operation = await res.json()

if (operation.status === 'completed') {
  console.log(operation.result.files[0].url)
} else if (operation.status === 'failed') {
  console.error(operation.error_message)
}

Генерация занимает минуты, а не секунды: запуск в максимальном качестве по четырём ракурсам у нас шёл около 12-13 минут. Опрашивайте статус раз в 15-30 секунд (не чаще раза в секунду для одной операции), пока он не станет completed или failed.

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

{
  "type": "file",
  "files": [
    {
      "url": "https://storage.bratuha.ru/results/hi3d-v3-0/model.glb",
      "name": "result"
    }
  ]
}

type - всегда "file".
files - массив из одного файла модели. url - ссылка на скачивание, name - служебное имя "result" без расширения.
Формат файла задаёт export_format, а расширение видно в самой ссылке (например, .glb или .stl). Сохраняя файл у себя, берите расширение из ссылки, а не из name.

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

Цена зависит только от качества resolution и списывается за одну модель:

`resolution`	Качество	Цена за модель
`2048quality`	Качество	300 ₽
`2048master`	Максимум	1300 ₽

Режим (одно фото или несколько ракурсов), число ракурсов, текстуры, PBR-материалы, число полигонов и формат файла на цену не влияют.

Стоимость списывается при создании операции и возвращается в поле cost.

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

POST /api/v1/operations не идемпотентен: повторный запрос создаёт новую операцию и снова списывает деньги. С ценой до 1300 ₽ за модель это особенно важно: не повторяйте POST при обрыве связи, а сначала проверьте, не создалась ли операция.
Операция выполняется асинхронно: сначала вы получаете queued, затем проверяете статус по id.
Ссылки на изображения - только внешние http/https URL, которые открываются без авторизации. Допустимые расширения: .jpg, .jpeg, .png, .webp. Ссылки на localhost и внутренние адреса сети не принимаются.
Каждое изображение - до 20 МБ.
Лучше всего работают фото одного предмета целиком, на однородном фоне, без обрезанных краёв и посторонних объектов. Для multiview снимайте ракурсы с одной высоты и одного расстояния, чтобы предмет на всех кадрах был одного масштаба.
Поля с картинками другого режима сервер не отправляет в модель: image_url в режиме multiview и виды в режиме image просто игнорируются.
Без текстур (enable_texture: false) PBR-материалы тоже отключаются, даже если передать enable_pbr: true.
Много полигонов - тяжёлый файл. Для веба и AR обычно хватает 100 000 - 500 000, для печати и крупных планов имеет смысл брать больше.
Формат STL хранит только геометрию, без цвета. Если нужна цветная модель, выбирайте glb, obj, fbx или usdz.
Если выключить enable_safety_checker, входные фото не проверяются перед обработкой. Правила сайта при этом продолжают действовать.
Ссылку на результат лучше сразу скачать и сохранить у себя.

true