Topaz Image Upscale API

Topaz Image Upscale API

Topaz Image Upscale увеличивает фото в 2 или 4 раза по каждой стороне и попутно убирает шум и следы сжатия. В зависимости от режима модель либо бережно сохраняет исходник, либо дорисовывает новые детали: подходит и для аккуратного увеличения хороших снимков, и для спасения маленьких мутных фото, и для картинок из нейросетей.

Режим выбирается параметром enhancement_type, внутри режима - конкретная модель. От режима, масштаба и размера исходника зависит цена, поэтому выбирайте режим осознанно: самый дорогой режим creative стоит по умолчанию.

Каждый вызов создаёт асинхронную операцию. После запуска нужно отдельно проверять статус по id.

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

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

Режимы (enhancement_type):

• precision - точное увеличение. Бережёт исходник, ничего не придумывает. Для хороших фото, скриншотов, графики и текста. Самый дешёвый режим.
• generative - генеративное увеличение. Дорисовывает детали на маленьких, сжатых и мутных фото. Модель Redefine дополнительно принимает текстовое задание.
• creative - творческое увеличение. Смело переосмысляет картинку и добавляет много новых деталей. Для изображений из нейросетей и иллюстраций. Самый дорогой режим.
• transparent - увеличение PNG с прозрачным фоном. Всегда увеличивает в 4 раза и сохраняет прозрачность.

Тело запроса

{
  "tool": "topaz-image-upscale",
  "input": {
    "enhancement_type": "precision",
    "image_url": "https://cdn.example.com/source-image-1.jpg",
    "precision_model": "Standard V2",
    "upscale_factor": "2",
    "output_format": "jpeg"
  }
}

• tool - slug нейросети, всегда "topaz-image-upscale".
• input - параметры запуска. Поля передаются напрямую внутри этого объекта, без дополнительной вложенности.
• Набор полей зависит от режима и модели. Поля, которые не относятся к выбранному режиму, не используются - их лучше не передавать. Если всё же передаёте, значения должны быть допустимыми, иначе запрос вернёт validation_error.

Параметры

Общие параметры

Режим precision

Режим generative

sharpen, denoise и subject_detection описаны в разделе режима precision.

Улучшение лиц (precision и generative)

Режим creative

Режим transparent

Кроме enhancement_type и image_url ничего передавать не нужно. Используйте PNG с прозрачным фоном - прозрачность сохранится в результате.

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

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

Точное увеличение (precision)

Самый дешёвый и быстрый вариант для обычных фото. Лица здесь не улучшаются отдельно.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "topaz-image-upscale",
  "input": {
    "enhancement_type": "precision",
    "image_url": "https://cdn.example.com/source-image-1.jpg",
    "precision_model": "Standard V2",
    "upscale_factor": "2",
    "output_format": "jpeg",
    "face_enhancement_mode": "off",
    "fix_compression": 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: 'topaz-image-upscale',
    input: {
      enhancement_type: 'precision',
      image_url: 'https://cdn.example.com/source-image-1.jpg',
      precision_model: 'Standard V2',
      upscale_factor: '2',
      output_format: 'jpeg',
      face_enhancement_mode: 'off',
      fix_compression: 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': 'topaz-image-upscale',
        'input': {
            'enhancement_type': 'precision',
            'image_url': 'https://cdn.example.com/source-image-1.jpg',
            'precision_model': 'Standard V2',
            'upscale_factor': '2',
            'output_format': 'jpeg',
            'face_enhancement_mode': 'off',
            'fix_compression': 0.5,
        },
    },
    timeout=30,
)

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

Генеративное увеличение маленького фото (generative, Wonder 3.5)

Подходит для старых фото с телефона, превью и картинок из мессенджеров. Лица улучшаются отдельно.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "topaz-image-upscale",
  "input": {
    "enhancement_type": "generative",
    "image_url": "https://cdn.example.com/small-photo.jpg",
    "generative_model": "Wonder 3.5",
    "generative_enhancement_strength": "auto",
    "upscale_factor": "4",
    "output_format": "jpeg",
    "face_enhancement_mode": "on",
    "face_enhancement_strength": 0.8,
    "face_enhancement_creativity": 0
  }
}'

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: 'topaz-image-upscale',
    input: {
      enhancement_type: 'generative',
      image_url: 'https://cdn.example.com/small-photo.jpg',
      generative_model: 'Wonder 3.5',
      generative_enhancement_strength: 'auto',
      upscale_factor: '4',
      output_format: 'jpeg',
      face_enhancement_mode: 'on',
      face_enhancement_strength: 0.8,
      face_enhancement_creativity: 0,
    },
  }),
})

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': 'topaz-image-upscale',
        'input': {
            'enhancement_type': 'generative',
            'image_url': 'https://cdn.example.com/small-photo.jpg',
            'generative_model': 'Wonder 3.5',
            'generative_enhancement_strength': 'auto',
            'upscale_factor': '4',
            'output_format': 'jpeg',
            'face_enhancement_mode': 'on',
            'face_enhancement_strength': 0.8,
            'face_enhancement_creativity': 0,
        },
    },
    timeout=30,
)

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

Генеративное увеличение с заданием (generative, Redefine)

Redefine дорисовывает детали по вашему описанию. Если писать задание не хочется, передайте generative_autoprompt: true.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "topaz-image-upscale",
  "input": {
    "enhancement_type": "generative",
    "image_url": "https://cdn.example.com/product-photo.png",
    "generative_model": "Redefine",
    "prompt": "Керамическая кружка на деревянном столе, чёткая фактура глазури и древесины",
    "generative_autoprompt": false,
    "generative_creativity": 3,
    "texture": 3,
    "sharpen": 0.5,
    "denoise": 0.5,
    "upscale_factor": "2",
    "output_format": "png",
    "face_enhancement_mode": "off"
  }
}'

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: 'topaz-image-upscale',
    input: {
      enhancement_type: 'generative',
      image_url: 'https://cdn.example.com/product-photo.png',
      generative_model: 'Redefine',
      prompt:
        'Керамическая кружка на деревянном столе, чёткая фактура глазури и древесины',
      generative_autoprompt: false,
      generative_creativity: 3,
      texture: 3,
      sharpen: 0.5,
      denoise: 0.5,
      upscale_factor: '2',
      output_format: 'png',
      face_enhancement_mode: 'off',
    },
  }),
})

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': 'topaz-image-upscale',
        'input': {
            'enhancement_type': 'generative',
            'image_url': 'https://cdn.example.com/product-photo.png',
            'generative_model': 'Redefine',
            'prompt': 'Керамическая кружка на деревянном столе, чёткая фактура глазури и древесины',
            'generative_autoprompt': False,
            'generative_creativity': 3,
            'texture': 3,
            'sharpen': 0.5,
            'denoise': 0.5,
            'upscale_factor': '2',
            'output_format': 'png',
            'face_enhancement_mode': 'off',
        },
    },
    timeout=30,
)

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

Творческое увеличение (creative, Bloom 2)

Для картинок из нейросетей и иллюстраций, где нужны новые детали, а точность исходника не важна.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "topaz-image-upscale",
  "input": {
    "enhancement_type": "creative",
    "image_url": "https://cdn.example.com/ai-illustration.png",
    "creative_model": "Bloom 2",
    "creative_autoprompt_mode": "on",
    "creative_creativity": 4,
    "color_preservation": true,
    "upscale_factor": "2",
    "output_format": "png"
  }
}'

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: 'topaz-image-upscale',
    input: {
      enhancement_type: 'creative',
      image_url: 'https://cdn.example.com/ai-illustration.png',
      creative_model: 'Bloom 2',
      creative_autoprompt_mode: 'on',
      creative_creativity: 4,
      color_preservation: true,
      upscale_factor: '2',
      output_format: 'png',
    },
  }),
})

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': 'topaz-image-upscale',
        'input': {
            'enhancement_type': 'creative',
            'image_url': 'https://cdn.example.com/ai-illustration.png',
            'creative_model': 'Bloom 2',
            'creative_autoprompt_mode': 'on',
            'creative_creativity': 4,
            'color_preservation': True,
            'upscale_factor': '2',
            'output_format': 'png',
        },
    },
    timeout=30,
)

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

Увеличение PNG с прозрачным фоном (transparent)

Для логотипов, стикеров и вырезанных товаров. Масштаб всегда 4x, результат - PNG с прозрачностью.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "topaz-image-upscale",
  "input": {
    "enhancement_type": "transparent",
    "image_url": "https://cdn.example.com/logo-transparent.png"
  }
}'

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: 'topaz-image-upscale',
    input: {
      enhancement_type: 'transparent',
      image_url: 'https://cdn.example.com/logo-transparent.png',
    },
  }),
})

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': 'topaz-image-upscale',
        'input': {
            'enhancement_type': 'transparent',
            'image_url': 'https://cdn.example.com/logo-transparent.png',
        },
    },
    timeout=30,
)

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

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

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

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "topaz-image-upscale",
  "cost": 14,
  "balance_after": 486,
  "created_at": "2026-09-30T12:46:50Z"
}

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

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "topaz-image-upscale",
  "cost": 14,
  "created_at": "2026-09-30T12:46:50Z",
  "completed_at": "2026-09-30T12:47:18Z",
  "result": {
    "type": "image",
    "urls": [
      "https://storage.bratuha.ru/results/topaz-image-upscale/image-1.jpeg"
    ]
  },
  "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.urls[0])
} else if (operation.status === 'failed') {
  console.error(operation.error_message)
}

Сколько ждать: precision и generative при 2x обычно готовы за 30-50 секунд, 4x с моделями High Fidelity - около двух минут, transparent - чуть больше минуты, creative - 2-3 минуты. Опрашивайте статус раз в 5 секунд (не чаще раза в секунду для одной операции), пока он не станет completed или failed.

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

После завершения Topaz Image Upscale возвращает:

{
  "type": "image",
  "urls": [
    "https://storage.bratuha.ru/results/topaz-image-upscale/image-1.jpeg"
  ]
}

• type - всегда "image".
• urls - массив из одной ссылки на увеличенное изображение.

Размер результата - исходник, умноженный на upscale_factor по каждой стороне: в нашей проверке фото 640×480 при "2" стало 1280×960. Формат - из output_format, в режиме transparent всегда PNG.

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

Цена считается по размеру готового результата: 14 ₽ за каждый начатый блок мегапикселей. Размер блока зависит от режима и модели. Размер исходника сервер определяет сам по файлу, передавать его не нужно.

Размер результата в мегапикселях = ширина × высота исходника × квадрат масштаба / 1 000 000. Для 2x это исходник × 4, для 4x - исходник × 16. Минимальная цена - 14 ₽.

Например, фото 1920×1080 при 2x даёт результат около 8,3 МП. В precision это один блок (14 ₽), в generative с Wonder 3 - два блока по 8 МП (28 ₽), в creative - пять блоков по 2 МП (70 ₽).

Готовые цены для частых размеров:

Остальные параметры - модель внутри режима (кроме разделения Wonder 3.5 и 3 от остальных генеративных), улучшение лиц, формат, креативность - на цену не влияют. Итоговая сумма приходит в поле cost сразу после создания операции.

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

• POST /api/v1/operations не идемпотентен: повторный запрос создаёт новую операцию и снова списывает деньги.
• Операция выполняется асинхронно: сначала вы получаете queued, затем проверяете статус по id.
• image_url принимает только внешние http/https ссылки с расширениями .jpg, .jpeg, .png, .webp. Ссылки на localhost и внутренние адреса сети не принимаются. Файл должен открываться по ссылке: сервер читает его размеры для расчёта цены, и если не может - вернёт ошибку validation_error без списания.
• Если не передать enhancement_type, запустится creative - самый дорогой режим. Всегда указывайте режим явно.
• upscale_factor передаётся строкой: "2" или "4". Число 4 без кавычек не пройдёт проверку.
• Для 4x на больших фото и в creative цена быстро растёт: 4x для снимка 12 МП в creative стоит больше тысячи рублей. Проверяйте cost в ответе на создание и считайте цену заранее по таблице.
• Очень большие результаты модель может не принять: например, 4x для фото 3672×4896 (результат почти 290 МП) завершился ошибкой параметров. Для крупных исходников используйте 2x.
• creative и generative дорисовывают детали: на мелких мутных фото могут поменяться черты лица, надписи и мелкие предметы. Если важна точность, берите precision, для маленьких фото - generative с Wonder 3.5.
• За один запрос обрабатывается одно изображение. Для пакета картинок создавайте по операции на каждую.
• Ссылку на результат лучше сразу скачать и сохранить у себя.