Документы и презентации через API

Создайте документ

Документы делает модель с типом document, её идентификатор в каталоге gamma. Она запускается задачей, prompt у неё обязателен.

curl https://epicai.ru/v1/tasks \
  -H "Authorization: Bearer $EPICAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gamma",
    "prompt": "Презентация о солнечной энергетике для школьников",
    "parameters": {"text_mode": "generate", "format": "presentation", "num_cards": 8, "language": "ru"}
  }'

{
  "id": "task_4b1c9d0e2f3a4b5c6d7e8f90",
  "object": "task",
  "type": "document",
  "model": "gamma",
  "status": "in_progress",
  "created_at": 1793114499,
  "started_at": 1793114499,
  "finished_at": null,
  "price": {"tokens": 23680, "charged": 0},
  "parameters": {"text_mode": "generate", "format": "presentation", "num_cards": 8, "language": "ru", "amount": "medium", "image_source": "noImages"}
}

В parameters вернулись и значения по умолчанию, которых вы не указывали. Задача идёт, пока документ не будет готов и выгружен. Опрашивайте её или укажите webhook_url. Опрос разобран в Задачах, вебхук в статье Вебхуки.

import os
import time
import requests

base = "https://epicai.ru/v1"
headers = {"Authorization": "Bearer " + os.environ["EPICAI_API_KEY"]}

reply = requests.post(base + "/tasks", headers=headers, json={
    "model": "gamma",
    "prompt": "Презентация о солнечной энергетике для школьников",
    "parameters": {"num_cards": 8},
})
reply.raise_for_status()
task = reply.json()

while task["status"] in ("queued", "in_progress"):
    time.sleep(5)
    task = requests.get(base + "/tasks/" + task["id"], headers=headers).json()

if task["status"] != "succeeded":
    raise SystemExit(task["error"]["message"])

with open("document.pdf", "wb") as out:
    out.write(requests.get(task["output"][0]["url"]).content)

Выберите способ

Способ задаёт parameters.text_mode, от него зависит смысл prompt.

text_mode	Что в prompt	Что делает модель
generate	Тема или задание	Пишет документ по теме. Значение по умолчанию
preserve	Готовый текст	Оформляет ваш текст и сохраняет его слова. Разбить текст на карточки можно строкой --- между блоками

Режима по шаблону в API нет. Значение template и поля шаблона и темы оформления дают 400 invalid_parameter, потому что шаблоны и темы хранятся в библиотеке сайта.

Настройте результат

Параметр	Значения
format	presentation (по умолчанию), document, social для поста, webpage для веб-страницы
num_cards	Слайдов, страниц или блоков, от 1 до 20, по умолчанию 5
language	Язык документа кодом из схемы модели, по умолчанию ru
amount	Объём текста на карточке: brief, medium, detailed или extensive. Только в режиме generate
tone, audience	Тон и аудитория свободным текстом до 200 знаков. Только в режиме generate
additional_instructions	Дополнительные требования до 1500 знаков
card_split	auto или inputTextBreaks, делить ли текст по строкам ---. Только в режиме preserve
image_source	noImages без картинок (по умолчанию), pexels стоковые фото, aiGenerated картинки нейросети
image_tier	economy, advanced или premium, только вместе с aiGenerated

Параметр, который при выбранных значениях не действует, отбрасывается без ошибки. Предельная длина prompt указана в поле prompt_max модели, больше даёт 400 prompt_too_long. Полную схему отдаёт GET /v1/models/gamma.

Заберите результат

Готовый документ лежит в output одним файлом PDF, независимо от format. Ссылка открывается без ключа и живёт 7 суток.

"output": [
  {"type": "document", "url": "https://epicai.ru/storage/api/4b1c9d0e2f3a4b5c6d7e8f90/1.pdf", "mime": "application/pdf", "bytes": 1523481}
]

Ссылки на редактор документа API не выдаёт, доступ к документу у вендора закрыт. Править документ после создания через API нельзя.

Цена

Цену задают число карточек и картинки. Каждая карточка добавляет одну и ту же сумму. Режим без картинок и стоковые фото стоят одинаково, а картинки нейросети дороже и растут в цене с каждым уровнем image_tier. Формат, язык и объём текста на цену не влияют. Точную сумму для ваших параметров даёт POST /v1/quote с тем же телом, что и у задачи.

{"model": "gamma", "parameters": {"num_cards": 10, "image_source": "aiGenerated", "image_tier": "economy"}}

Цена фиксируется при создании задачи, целиком резервируется и после завершения не меняется. Если документ не создан, токены не списываются. Как это устроено, объясняет статья Цена задачи.