Hunyuan World 1.0 API

Hunyuan World 1.0 API

Hunyuan World 1.0 от Tencent работает с 3D-сценами в два шага. Сначала из обычной картинки и текстового описания получается панорама на 360°: сцена, развёрнутая вокруг зрителя. Потом из панорамы можно собрать «мир» - набор 3D-сеток по слоям (фон, передний план, небо), по которому можно перемещать камеру и смотреть на сцену с разных ракурсов.

Панорама подходит для виртуальных туров, фонов в 3D-редакторах и VR, скайбоксов в играх. «Мир» - заготовка для сцены в Blender, игровом движке или веб-просмотрщике.

Каждый вызов создаёт асинхронную операцию и идёт долго: панорама - 7-13 минут, мир - от 12 до 22 минут. После запуска проверяйте статус по id.

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

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

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

• panorama - панорама 360° по картинке и заданию prompt. Результат - изображение PNG.
• world - 3D-мир по готовой панораме и меткам объектов (labels_fg1, labels_fg2, classes). Результат - ZIP-архив с файлами сцены.

Обычный порядок работы: запустить panorama, взять ссылку на полученную панораму и передать её в image_url запуска world.

Тело запроса

{
  "tool": "hunyuan-world-1-0",
  "input": {
    "hunyuan_generation_type": "panorama",
    "image_url": "https://cdn.example.com/workshop-photo.jpg",
    "prompt": "Мастерская часовщика целиком, вокруг зрителя"
  }
}

• tool - slug нейросети, всегда "hunyuan-world-1-0".
• input - параметры запуска. Поля передаются напрямую внутри этого объекта, без дополнительной вложенности.
• Набор полей зависит от сценария: prompt нужен только для panorama, labels_fg1, labels_fg2, classes и export_drc - только для world.

Параметры

Метки labels_fg1 и labels_fg2 помогают модели разрезать панораму на слои: объекты из первого списка попадут в ближний слой, из второго - в следующий, всё остальное уйдёт в фон и небо. Называйте крупные предметы, которые действительно видны на панораме.

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

Панорама 360° по картинке

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "hunyuan-world-1-0",
  "input": {
    "hunyuan_generation_type": "panorama",
    "image_url": "https://cdn.example.com/workshop-photo.jpg",
    "prompt": "Мастерская часовщика целиком, вокруг зрителя: верстак с разобранными часами у окна, на стенах старые часы с маятниками, полки с инструментами, деревянная дверь. Тёплый свет лампы, фотореалистично."
  }
}'

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: 'hunyuan-world-1-0',
    input: {
      hunyuan_generation_type: 'panorama',
      image_url: 'https://cdn.example.com/workshop-photo.jpg',
      prompt: 'Мастерская часовщика целиком, вокруг зрителя: верстак с разобранными часами у окна, на стенах старые часы с маятниками, полки с инструментами, деревянная дверь. Тёплый свет лампы, фотореалистично.',
    },
  }),
})

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': 'hunyuan-world-1-0',
        'input': {
            'hunyuan_generation_type': 'panorama',
            'image_url': 'https://cdn.example.com/workshop-photo.jpg',
            'prompt': 'Мастерская часовщика целиком, вокруг зрителя: верстак с разобранными часами у окна, на стенах старые часы с маятниками, полки с инструментами, деревянная дверь. Тёплый свет лампы, фотореалистично.',
        },
    },
    timeout=30,
)

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

3D-мир по панораме

В image_url - панорама 2:1, например результат предыдущего запуска.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "hunyuan-world-1-0",
  "input": {
    "hunyuan_generation_type": "world",
    "image_url": "https://cdn.example.com/workshop-panorama.png",
    "labels_fg1": "workbench, lamp",
    "labels_fg2": "wall clocks, shelves",
    "classes": "indoor",
    "export_drc": 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: 'hunyuan-world-1-0',
    input: {
      hunyuan_generation_type: 'world',
      image_url: 'https://cdn.example.com/workshop-panorama.png',
      labels_fg1: 'workbench, lamp',
      labels_fg2: 'wall clocks, shelves',
      classes: 'indoor',
      export_drc: false,
    },
  }),
})

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': 'hunyuan-world-1-0',
        'input': {
            'hunyuan_generation_type': 'world',
            'image_url': 'https://cdn.example.com/workshop-panorama.png',
            'labels_fg1': 'workbench, lamp',
            'labels_fg2': 'wall clocks, shelves',
            'classes': 'indoor',
            'export_drc': False,
        },
    },
    timeout=30,
)

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

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

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

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "hunyuan-world-1-0",
  "cost": 50,
  "balance_after": 950,
  "created_at": "2026-09-30T21:29:07Z"
}

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

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "hunyuan-world-1-0",
  "cost": 50,
  "created_at": "2026-09-25T20:04:46Z",
  "completed_at": "2026-09-25T20:17:59Z",
  "result": {
    "type": "image",
    "urls": [
      "https://storage.bratuha.ru/results/hunyuan-world-1-0/panorama.png"
    ]
  },
  "error_message": null
}

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

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "hunyuan-world-1-0",
  "cost": 50,
  "created_at": "2026-09-30T21:29:07Z",
  "completed_at": "2026-09-30T21:50:43Z",
  "result": {
    "type": "file",
    "files": [
      {
        "url": "https://storage.bratuha.ru/results/hunyuan-world-1-0/1790805010848-qwtad27y",
        "name": "result"
      }
    ]
  },
  "error_message": null
}

Обратите внимание: у ссылки на архив мира нет расширения .zip, а name - служебное "result". Это ZIP-архив, сохраняйте его под своим именем с расширением .zip.

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

Сохраните 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') {
  if (operation.result.type === 'image') {
    console.log('Панорама:', operation.result.urls[0])
  } else {
    console.log('Архив мира:', operation.result.files[0].url)
  }
} else if (operation.status === 'failed') {
  console.error(operation.error_message)
}

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

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

Формат зависит от сценария.

Панорама (panorama)

{
  "type": "image",
  "urls": [
    "https://storage.bratuha.ru/results/hunyuan-world-1-0/panorama.png"
  ]
}

• type - "image".
• urls - массив из одной ссылки на PNG-панораму 1920×960 (соотношение 2:1, равнопромежуточная проекция). Её можно сразу открыть в просмотрщике 360°, использовать как скайбокс или передать в image_url сценария world.

Мир (world)

{
  "type": "file",
  "files": [
    {
      "url": "https://storage.bratuha.ru/results/hunyuan-world-1-0/1790805010848-qwtad27y",
      "name": "result"
    }
  ]
}

• type - "file".
• files - массив из одного файла: ZIP-архив со сценой. Ссылка без расширения, name всегда "result", поэтому тип файла определяйте сами: это ZIP.

Архив большой: в нашей проверке он весил 464 МБ, а в распакованном виде - около 760 МБ. Внутри:

PLY-сетки открываются в Blender, MeshLab, CloudCompare и загружаются в three.js через PLYLoader. По fg1.json и fg2.json удобно проверить, распознала ли модель нужные объекты: если метки там нет, объект остался частью фона.

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

Цена фиксированная - 50 ₽ за запуск в любом сценарии:

Длина задания, метки, export_drc и размер исходной картинки на цену не влияют. Полный путь «картинка → панорама → мир» стоит 100 ₽ за два запуска.

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

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

• POST /api/v1/operations не идемпотентен: повторный запрос создаёт новую операцию и снова списывает деньги.
• Операция выполняется асинхронно: сначала вы получаете queued, затем проверяете статус по id.
• image_url принимает только внешние http/https ссылки с расширениями .jpg, .jpeg, .png, .webp, которые открываются без авторизации. Ссылки на localhost и внутренние адреса сети не принимаются.
• Для world подавайте именно панораму 2:1. С обычным кадром (например, 16:9) операция формально завершится, но слои получатся неправильными: модель считает картинку развёрткой на 360° и режет её не по тем объектам.
• В panorama описывайте сцену целиком, со всех сторон: картинка задаёт стиль и часть сцены, а остальное модель дорисовывает по заданию.
• Метки labels_fg1, labels_fg2 и classes лучше писать по-английски, короткими названиями предметов.
• Архив мира весит сотни мегабайт: закладывайте время и место на скачивание, для веба сетки обычно нужно прореживать.
• Ссылка на архив мира без расширения .zip. Не определяйте тип файла по ссылке или name - для world это всегда ZIP.
• Модель ищет на панораме только те объекты, которые вы перечислили в метках. Если объект не нашёлся (его нет в fg1.json или fg2.json), он останется частью фона.
• Ссылку на результат лучше сразу скачать и сохранить у себя.