Muse Image API

Краткое практическое введение

Muse Image рисует изображения по текстовому заданию и меняет готовые картинки по инструкции, опираясь на 1-9 референсов. Каждый запуск стоит 1 ₽, поэтому через API её удобно использовать для массовых и черновых задач:

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

Режим определяется составом запроса: без image_urls - генерация по тексту, со ссылками - работа по референсам. Каждый вызов создаёт асинхронную операцию: в ответ сразу приходят id и стартовый статус, а ссылку на готовую картинку вы забираете запросом проверки статуса.

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

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

Сценарии:

• генерация по тексту - prompt и при желании aspect_ratio;
• правка по одному фото - prompt и одна ссылка в image_urls;
• сцена из нескольких референсов - prompt и 2-9 ссылок в image_urls.

Тело запроса

Базовая форма запроса:

{
  "tool": "muse-image",
  "input": {
    "...": "..."
  }
}

• tool - slug нейросети, для этой модели всегда "muse-image".
• input - параметры запуска. Поля передаются прямо внутри input, без дополнительной вложенности.
• Набор полей зависит от сценария: image_urls добавляйте только когда есть референсы.

Параметры

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

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

Сценарий 1. Генерация по тексту

Нужна только текстовая подсказка и, если важно, пропорции.

cURL

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

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: 'muse-image',
    input: {
      prompt:
        'Красная керамическая чашка на белом столе, мягкий студийный свет, предметная съёмка, без надписей',
      aspect_ratio: '4:3',
    },
  }),
})

const data = await response.json()
console.log(data)

Python

import requests

response = requests.post(
    "https://bratuha.ru/api/v1/operations",
    headers={
        "Authorization": "Bearer brth_ваш_ключ",
        "Content-Type": "application/json",
    },
    json={
        "tool": "muse-image",
        "input": {
            "prompt": "Красная керамическая чашка на белом столе, мягкий студийный свет, предметная съёмка, без надписей",
            "aspect_ratio": "4:3",
        },
    },
    timeout=30,
)

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

Сценарий 2. Правка по одному фото

Передайте одну ссылку в image_urls и опишите, что изменить и что оставить как есть. Без aspect_ratio модель сохранит пропорции исходника.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "muse-image",
    "input": {
      "prompt": "Оставь чашку с фото как есть и поставь её на деревянный стол в кафе, тёплый дневной свет из окна",
      "image_urls": [
        "https://cdn.example.com/source-image-1.jpg"
      ]
    }
  }'

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: 'muse-image',
    input: {
      prompt:
        'Оставь чашку с фото как есть и поставь её на деревянный стол в кафе, тёплый дневной свет из окна',
      image_urls: ['https://cdn.example.com/source-image-1.jpg'],
    },
  }),
})

const data = await response.json()
console.log(data)

Python

import requests

response = requests.post(
    "https://bratuha.ru/api/v1/operations",
    headers={
        "Authorization": "Bearer brth_ваш_ключ",
        "Content-Type": "application/json",
    },
    json={
        "tool": "muse-image",
        "input": {
            "prompt": "Оставь чашку с фото как есть и поставь её на деревянный стол в кафе, тёплый дневной свет из окна",
            "image_urls": ["https://cdn.example.com/source-image-1.jpg"],
        },
    },
    timeout=30,
)

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

Сценарий 3. Сцена из нескольких референсов

Передайте от 2 до 9 ссылок. Главный исходник ставьте первым и в prompt объясните, что взять с каждой картинки.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "muse-image",
    "input": {
      "prompt": "Рюкзак с первого изображения лежит на скамейке в парке со второго изображения, осенний вечер, рекламный кадр",
      "image_urls": [
        "https://cdn.example.com/source-image-1.jpg",
        "https://cdn.example.com/source-image-2.png"
      ],
      "aspect_ratio": "9:16"
    }
  }'

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: 'muse-image',
    input: {
      prompt:
        'Рюкзак с первого изображения лежит на скамейке в парке со второго изображения, осенний вечер, рекламный кадр',
      image_urls: [
        'https://cdn.example.com/source-image-1.jpg',
        'https://cdn.example.com/source-image-2.png',
      ],
      aspect_ratio: '9:16',
    },
  }),
})

const data = await response.json()
console.log(data)

Python

import requests

response = requests.post(
    "https://bratuha.ru/api/v1/operations",
    headers={
        "Authorization": "Bearer brth_ваш_ключ",
        "Content-Type": "application/json",
    },
    json={
        "tool": "muse-image",
        "input": {
            "prompt": "Рюкзак с первого изображения лежит на скамейке в парке со второго изображения, осенний вечер, рекламный кадр",
            "image_urls": [
                "https://cdn.example.com/source-image-1.jpg",
                "https://cdn.example.com/source-image-2.png",
            ],
            "aspect_ratio": "9:16",
        },
    },
    timeout=30,
)

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

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

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

{
  "id": "3f6a2d18-9c4b-4e71-a5d0-8b2e7c1f4a96",
  "status": "queued",
  "tool": "muse-image",
  "cost": 1,
  "balance_after": 499,
  "created_at": "2026-11-02T08:00:00.000Z"
}

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

{
  "id": "3f6a2d18-9c4b-4e71-a5d0-8b2e7c1f4a96",
  "status": "completed",
  "tool": "muse-image",
  "cost": 1,
  "created_at": "2026-11-02T08:00:00.000Z",
  "completed_at": "2026-11-02T08:00:30.000Z",
  "result": {
    "type": "image",
    "urls": [
      "https://storage.bratuha.ru/results/muse-image/image-1.webp"
    ]
  },
  "error_message": null
}

Ответ при ошибке выполнения

{
  "id": "3f6a2d18-9c4b-4e71-a5d0-8b2e7c1f4a96",
  "status": "failed",
  "tool": "muse-image",
  "cost": 1,
  "created_at": "2026-11-02T08:00:00.000Z",
  "completed_at": "2026-11-02T08:00:15.000Z",
  "result": null,
  "error_message": "Не удалось выполнить операцию"
}

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

Статус проверяется по id, который пришёл в ответ на создание операции. Сохраните его - без id результат конкретного запуска не получить. Опрашивать удобно раз в 3-5 секунд, пока статус не станет completed или failed.

cURL

curl -H "Authorization: Bearer brth_ваш_ключ" \
  https://bratuha.ru/api/v1/operations/3f6a2d18-9c4b-4e71-a5d0-8b2e7c1f4a96

JavaScript / TypeScript

const operationId = '3f6a2d18-9c4b-4e71-a5d0-8b2e7c1f4a96'

const response = await fetch(
  `https://bratuha.ru/api/v1/operations/${operationId}`,
  {
    headers: {
      Authorization: 'Bearer brth_ваш_ключ',
    },
  },
)

const operation = await response.json()
console.log(operation)

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

После успешного выполнения в result приходит объект изображения:

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

urls - массив ссылок. Один запуск создаёт одно изображение в формате WebP, поэтому ссылка в массиве одна.

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

• Цена фиксированная: 1 ₽ за изображение.
• Пропорции и число референсов цену не меняют.

Примеры:

• без изображений, aspect_ratio = 16:9 - 1 ₽;
• одна ссылка в image_urls - 1 ₽;
• девять ссылок в image_urls - 1 ₽.

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

• Передайте UUID в заголовке Idempotency-Key: повтор одного запроса в течение 24 часов вернёт исходную операцию без повторного списания. Повтор без этого заголовка создаёт новую операцию.
• Передайте max_price в теле запроса, чтобы сервер отклонил запуск дороже согласованной суммы до списания.
• Операция выполняется асинхронно - готовой картинки в ответе на POST нет, используйте GET /api/v1/operations/{id}.
• Для image_urls нужны внешние http/https URL, доступные из интернета без входа в аккаунт. Локальные пути, localhost, blob: и data: не подходят.
• Не больше 9 изображений в image_urls, все вместе - до 11 МБ. Подходят .jpg, .jpeg, .png и .webp.
• Один запуск - одно изображение. Чтобы получить несколько вариантов, создайте несколько операций.
• Маски, негативного промпта, seed и выбора разрешения нет: чтобы изменить часть картинки, словами опишите, что именно поменять и что оставить.
• Задания проверяются перед запуском: запросы с несовершеннолетними в сексуальном контексте и с насилием над детьми отклоняются до списания денег.