Z-Image API

Z-Image API

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

Сценарии:

• Генерация по тексту - запуск без image.
• Генерация по референсу - запуск с одной ссылкой в image и настройкой силы изменений strength.

Есть две версии модели: turbo - самая быстрая и дешёвая, base - аккуратнее в деталях и умеет учитывать негативный промпт.

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

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

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

Версия модели выбирается параметром model_tier: turbo или base. Режим с референсом включается просто наличием поля image.

Тело запроса

{
  "tool": "z-image",
  "input": {
    "model_tier": "turbo",
    "prompt": "...",
    "aspect_ratio": "1:1",
    "strength": 0.6,
    "output_format": "jpeg"
  }
}

• tool - slug нейросети, всегда "z-image".
• input - параметры запуска. Все поля передаются прямо внутри этого объекта, без дополнительной вложенности.

Параметры

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

Генерация по тексту

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "z-image",
  "input": {
    "model_tier": "turbo",
    "prompt": "Портрет старого морского капитана: белая фуражка с якорем, тёмно-синий бушлат, короткая белая борода, за спиной маяк на закате. Реалистичное фото, крупный план.",
    "aspect_ratio": "3:4",
    "output_format": "jpeg"
  }
}'

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: 'z-image',
    input: {
      model_tier: 'turbo',
      prompt:
        'Портрет старого морского капитана: белая фуражка с якорем, тёмно-синий бушлат, короткая белая борода, за спиной маяк на закате. Реалистичное фото, крупный план.',
      aspect_ratio: '3:4',
      output_format: 'jpeg',
    },
  }),
})

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': 'z-image',
        'input': {
            'model_tier': 'turbo',
            'prompt': 'Портрет старого морского капитана: белая фуражка с якорем, тёмно-синий бушлат, короткая белая борода, за спиной маяк на закате. Реалистичное фото, крупный план.',
            'aspect_ratio': '3:4',
            'output_format': 'jpeg',
        },
    },
    timeout=30,
)

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

Генерация по референсу

Модель берёт картинку из image за основу и меняет её по заданию. При strength около 0.6 результат остаётся очень близок к исходнику, для заметной смены стиля поднимайте значение до 0.8-1.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "z-image",
  "input": {
    "model_tier": "turbo",
    "prompt": "Та же сцена в стиле акварельной иллюстрации, мягкие пастельные цвета",
    "image": "https://cdn.example.com/portrait-1.jpg",
    "aspect_ratio": "1:1",
    "strength": 0.85,
    "output_format": "jpeg"
  }
}'

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: 'z-image',
    input: {
      model_tier: 'turbo',
      prompt: 'Та же сцена в стиле акварельной иллюстрации, мягкие пастельные цвета',
      image: 'https://cdn.example.com/portrait-1.jpg',
      aspect_ratio: '1:1',
      strength: 0.85,
      output_format: 'jpeg',
    },
  }),
})

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': 'z-image',
        'input': {
            'model_tier': 'turbo',
            'prompt': 'Та же сцена в стиле акварельной иллюстрации, мягкие пастельные цвета',
            'image': 'https://cdn.example.com/portrait-1.jpg',
            'aspect_ratio': '1:1',
            'strength': 0.85,
            'output_format': 'jpeg',
        },
    },
    timeout=30,
)

print(response.json())

Версия Base с негативным промптом

Негативный промпт работает только в base и только вместе с use_negative_prompt: true.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "z-image",
  "input": {
    "model_tier": "base",
    "prompt": "Уютная кухня в скандинавском стиле, утренний свет из окна, на столе ваза с полевыми цветами, вид сбоку",
    "aspect_ratio": "16:9",
    "output_format": "png",
    "use_negative_prompt": true,
    "negative_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: 'z-image',
    input: {
      model_tier: 'base',
      prompt:
        'Уютная кухня в скандинавском стиле, утренний свет из окна, на столе ваза с полевыми цветами, вид сбоку',
      aspect_ratio: '16:9',
      output_format: 'png',
      use_negative_prompt: true,
      negative_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': 'z-image',
        'input': {
            'model_tier': 'base',
            'prompt': 'Уютная кухня в скандинавском стиле, утренний свет из окна, на столе ваза с полевыми цветами, вид сбоку',
            'aspect_ratio': '16:9',
            'output_format': 'png',
            'use_negative_prompt': True,
            'negative_prompt': 'люди, текст, водяные знаки, размытие',
        },
    },
    timeout=30,
)

print(response.json())

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

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

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "z-image",
  "cost": 1,
  "balance_after": 499,
  "created_at": "2026-09-30T12:45:51.962599+00:00"
}

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

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "z-image",
  "cost": 1,
  "created_at": "2026-09-30T12:45:51.962599+00:00",
  "completed_at": "2026-09-30T12:46:07.66383+00:00",
  "result": {
    "type": "image",
    "urls": [
      "https://storage.bratuha.ru/results/z-image/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

async function waitForResult(id: string) {
  while (true) {
    const response = await fetch(`https://bratuha.ru/api/v1/operations/${id}`, {
      headers: { Authorization: 'Bearer brth_ваш_ключ' },
    })
    const operation = await response.json()
    if (operation.status === 'completed' || operation.status === 'failed') {
      return operation
    }
    await new Promise((resolve) => setTimeout(resolve, 3000))
  }
}

Статус меняется с queued на processing, а затем на completed или failed. Обычно картинка готова за 15-25 секунд. Опрашивать одну операцию можно не чаще раза в секунду, разумный интервал - 3 секунды.

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

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

• type - всегда "image".
• urls - массив с одной ссылкой на картинку. Расширение файла совпадает с output_format: jpeg, png или webp.

Размер результата - около 1 мегапикселя: длинная сторона 1024 пикселя. Без референса размер задаёт aspect_ratio, с референсом картинка обычно сохраняет пропорции исходника.

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

Цена фиксирована за одно изображение и зависит только от версии модели. Референс, strength, формат, пропорции и негативный промпт на цену не влияют.

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

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

• POST /api/v1/operations не идемпотентен: каждый повторный запрос создаёт новую оплаченную операцию. Если ответ потерялся, не повторяйте запрос вслепую.
• Все операции асинхронные: сначала приходит queued, результат забирается по id.
• В image передаётся одна внешняя ссылка http/https на файл jpg, jpeg, png или webp. Ссылка должна открываться без авторизации.
• Один запуск - одно изображение. Для нескольких вариантов отправьте несколько запросов.
• С референсом значение strength решает почти всё: при низких значениях картинка почти не меняется, при высоких модель может уйти далеко от исходника. Начните с 0.8 и подстройте.
• use_negative_prompt и negative_prompt действуют только в версии base. В turbo они не учитываются.
• Как и у других генераторов, возможны промахи в мелочах: пальцы, мелкий текст, лишние детали на фоне. base справляется с ними лучше turbo.