Документация GroUvi API: приватный режим и файлы

Адреса и ключи

Ключ передаётся в заголовке Authorization: Bearer sk-.... Ключи создаются в консоли, раздел «Ключи API»: для приватного режима выберите группу «Приватная — маскировка персональных данных».

Запросы к моделям

POST /v1/chat/completions, как в OpenAI, с потоковой выдачей и инструментами. В приватном режиме в тело можно добавить два поля: grouvi_mask.terms — свои слова, которые надо скрыть, и grouvi_mask.off — типы данных, которые остаются открытыми. Ответ приходит с настоящими данными на местах и полем grouvi_mask.masked: что скрыто, по типам.

from openai import OpenAI

client = OpenAI(base_url="https://ai.grouvi.online/v1", api_key="sk-...")
reply = client.chat.completions.create(
    model="minimax-m3",
    messages=[{"role": "user", "content": "Напиши письмо Кузнецову Дмитрию, паспорт 4515 236781"}],
    extra_body={"grouvi_mask": {"terms": ["Орион"], "off": ["DATE"]}},
)
print(reply.choices[0].message.content)   # настоящие данные уже на месте

Файлы в запросе к модели

В приватном режиме документ можно положить прямо в сообщение — частью file с file_data, как в OpenAI. Мы читаем его у себя, маскируем вместе с перепиской, и модель получает его текст. Картинки уходят распознанным текстом.

import base64

data = base64.b64encode(open("договор.pdf", "rb").read()).decode()
reply = client.chat.completions.create(
    model="minimax-m3",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Кто заказчик и какой у него ИНН?"},
        {"type": "file", "file": {"filename": "договор.pdf",
                                  "file_data": f"data:application/pdf;base64,{data}"}},
    ]}],
)

Файловый API

POST /v1/files/mask принимает документ и возвращает тот же документ с заменёнными данными, его текст для модели и vault — зашифрованную таблицу замен. POST /v1/files/restore возвращает настоящие данные: в файл, который поправила модель (multipart: file и vault), или в текст (JSON: text и vault). Мы ничего не храним: vault лежит у вас и открывается только тем ключом, которым создан.

import base64, requests

API = "https://ai.grouvi.online/v1"
KEY = {"Authorization": "Bearer sk-..."}

# 1. договор целиком: тот же .docx назад и текст для модели
r = requests.post(f"{API}/files/mask", headers=KEY,
                  files={"file": open("договор.docx", "rb")},
                  data={"terms": "Орион, Альфа-Строй"}).json()
open("договор-маска.docx", "wb").write(base64.b64decode(r["file"]))
print(r["report"])          # что скрыто, по типам
vault = r["vault"]          # сохраните: без него данные не вернуть

# 2. модель поправила договор: настоящие имена и реквизиты обратно в файл
back = requests.post(f"{API}/files/restore", headers=KEY,
                     files={"file": open("договор-правки.docx", "rb")},
                     data={"vault": vault}).json()
open("договор-итог.docx", "wb").write(base64.b64decode(back["file"]))

# 3. или вернуть данные в ответ модели
text = requests.post(f"{API}/files/restore", headers=KEY,
                     json={"vault": vault, "text": "Ответ модели..."}).json()["text"]

curl "https://ai.grouvi.online/v1/files/mask?download=1" \
  -H "Authorization: Bearer sk-..." \
  -F file=@скан.pdf -D headers.txt -o скан-маска.pdf
# в headers.txt: X-Grouvi-Vault (ключ возврата) и X-Grouvi-Report (что скрыто)

Форматы

• Word .docxТекст, таблицы, колонтитулы, сноски, примечания вместе с авторами, исправления, надписи, ссылки, свойства документа. Оформление сохраняется.
• Excel .xlsxЯчейки, строковые результаты формул и строки внутри них, комментарии, кэши сводных таблиц, колонтитулы. Числа и формулы не трогаем.
• PowerPoint .pptxСлайды, заметки, комментарии и диаграммы.
• PDFТекст вырезается из файла, а подмена ставится на то же место. Поля форм, аннотации, ссылки, закладки и метаданные тоже очищаются.
• Сканы и фотоТекст распознаётся на нашем сервере в Москве, данные закрашиваются на картинке; у скана в PDF появляется текстовый слой для поиска.
• CSV, JSON, TXTCSV сохраняет разделитель и кавычки; в JSON маскируются только строковые значения.

Старые .doc, .xls и .ppt не принимаются — с подсказкой сохранить их в новом формате. Файл, текст которого не удалось проверить полностью, отклоняется, а не возвращается наполовину замаскированным.

Ошибки

Ошибка приходит в виде {"error": {"code": "...", "message": "..."}}; message написан для людей.

Лимиты

• Файлы: до 25 МБ, до 30 файлов в минуту на ключ, PDF до 300 страниц.
• Запросы к моделям: лимит аккаунта в минуту указан в консоли.
• Сканы: около 5–10 секунд на страницу.