Фирменно API

Обзор

Фирменно API позволяет встроить генерацию корпоративных портретов в ваше приложение, HRIS или процесс онбординга. Загружаете фото сотрудника — получаете два готовых варианта в едином фирменном стиле вашей организации. Всё тарифицируется через кредитный баланс.

Аутентификация

Все запросы требуют передачи API-ключа в заголовке Authorization:

Authorization: Bearer firm_live_<ваш-ключ>

Ключи создаются в настройках организации → API-ключи. Ключ показывается один раз при создании — сохраните его. При отсутствии или неверном ключе сервер вернёт 401 Unauthorized.

Эндпоинты

GET /api/v1/balance

Возвращает текущий кредитный баланс организации.

curl https://firmenno.ru/api/v1/balance \
  -H "Authorization: Bearer firm_live_<ключ>"

Ответ

{
  "credits": 47
}

GET /api/v1/presets

Возвращает список пресетов фотостилей вашей организации. Активный пресет помечен флагом active: true.

curl https://firmenno.ru/api/v1/presets \
  -H "Authorization: Bearer firm_live_<ключ>"

Ответ

{
  "presets": [
    {
      "id":               "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name":             "Корпоратив: Светлый",
      "active":           true,
      "background_color": "#F5F5F7",
      "aspect_ratio":     "4:5"
    }
  ]
}

POST /api/v1/generate

Генерирует корпоративный портрет по пресету организации. Стоимость: 1 кредит — возвращает 2 варианта на выбор.

curl -X POST https://firmenno.ru/api/v1/generate \
  -H "Authorization: Bearer firm_live_<ключ>" \
  -H "Content-Type: application/json" \
  -d '{
    "photo_url":   "https://cdn.example.com/ivanov.jpg",
    "preset_id":   "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "employee_id": "emp_1234"
  }'

Ответ (200)

{
  "variants": [
    { "index": 1, "url": "https://storage.firmenno.ru/results/abc_v1.jpg" },
    { "index": 2, "url": "https://storage.firmenno.ru/results/abc_v2.jpg" }
  ],
  "preset_id":    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "credits_used": 1,
  "credits_left": 46
}

Генерация занимает 60–180 секунд — увеличьте timeout HTTP-клиента до 300 с. При ошибке кредит автоматически возвращается на баланс.

Коды ошибок

Формат ошибки

{
  "error":     "Insufficient credits",
  "retryable": false
}

retryable: true — повторный запрос может успешно выполниться (временная перегрузка AI-провайдера).

Биллинг

API использует тот же кредитный баланс, что и веб-интерфейс. Пополните баланс в настройках организации или через подписку.

При ошибке генерации кредит автоматически возвращается. Текущий баланс доступен через GET /api/v1/balance и в поле credits_left каждого ответа генерации.

Примеры кода

const BASE = "https://firmenno.ru/api/v1";
const KEY  = process.env.FIRMENNO_API_KEY; // firm_live_...

// 1. Получить активный пресет
const presetsRes = await fetch(`${BASE}/presets`, {
  headers: { Authorization: `Bearer ${KEY}` },
});
const { presets } = await presetsRes.json();
const preset = presets.find((p: { active: boolean }) => p.active);

// 2. Сгенерировать портрет нового сотрудника
const res = await fetch(`${BASE}/generate`, {
  method: "POST",
  headers: {
    Authorization:  `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    photo_url:   "https://cdn.yourapp.ru/uploads/ivanov.jpg",
    preset_id:   preset.id,
    employee_id: "emp_1234",
  }),
  // Генерация занимает до 3 минут
  signal: AbortSignal.timeout(300_000),
});

const { variants, credits_left } = await res.json();
console.log("Вариант 1:", variants[0].url);
console.log("Вариант 2:", variants[1].url);
console.log("Остаток кредитов:", credits_left);

import os
import httpx

BASE = "https://firmenno.ru/api/v1"
KEY  = os.environ["FIRMENNO_API_KEY"]  # firm_live_...
H    = {"Authorization": f"Bearer {KEY}"}

# Получить активный пресет
presets = httpx.get(f"{BASE}/presets", headers=H).json()["presets"]
preset_id = next(p["id"] for p in presets if p["active"])

# Генерация (timeout=300 — до 3 минут)
r = httpx.post(
    f"{BASE}/generate",
    headers={**H, "Content-Type": "application/json"},
    json={
        "photo_url":   "https://cdn.yourapp.ru/uploads/ivanov.jpg",
        "preset_id":   preset_id,
        "employee_id": "emp_1234",
    },
    timeout=300,
)
r.raise_for_status()
data = r.json()
print("Вариант 1:", data["variants"][0]["url"])
print("Вариант 2:", data["variants"][1]["url"])
print(f"Списано: {data['credits_used']}, осталось: {data['credits_left']}")

Получить доступ

API доступен всем клиентам на тарифе Команда и выше. Создайте аккаунт, настройте фотостиль и сгенерируйте ключ — займёт 10 минут.