Документация Developer API

Через API доступно то же, что и в студии: картинки, видео, 3D-модели, распознавание речи и запросы к языковым моделям. Тарифы одинаковые, деньги списываются с того же баланса, что и при работе через сайт. Отдельного счёта для API нет.

API устроен по правилам REST: вы отправляете HTTP-запрос с ключом в заголовке и получаете JSON в ответ. Никаких SDK ставить не обязательно — хватит curl, requests, axios или узла HTTP в n8n.

Шаг 1. Получить ключ

Зайдите в Настройки → API и нажмите «Создать ключ». Секрет показывается один раз — мы храним только его отпечаток и восстановить исходную строку не можем. Потеряли — отзывайте ключ и создавайте новый.

Шаг 2. Проверить, что ключ работает

Самый безопасный первый запрос — узнать баланс. Он ничего не стоит и сразу показывает, принят ли ключ.

export ARK_KEY="ark_live_..."

curl -sS -H "Authorization: Bearer $ARK_KEY" \
  https://arckep.ru/api/v1/balance

В ответе — остаток в рублях. Если пришла ошибка с кодом UNAUTHORIZED, значит ключ скопирован не полностью или уже отозван.

Шаг 3. Первая генерация

Картинки, видео и 3D делаются асинхронно: запрос возвращается сразу, а результат появляется позже. В ответ приходит номер задачи, по которому можно спрашивать статус.

curl -sS -X POST https://arckep.ru/api/v1/images/generations \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "красное яблоко на мраморном столе"
  }'

curl -sS -H "Authorization: Bearer $ARK_KEY" \
  https://arckep.ru/api/v1/images/generations/123

Ключ передаётся в заголовке Authorization с префиксом Bearer. Все ключи начинаются с ark_live_.

Authorization: Bearer ark_live_<ваш секрет>

Права (scopes)

У каждого ключа есть набор прав. Это защита от чужой ошибки: ключ, выданный для картинок, не сможет потратить деньги на видео или на языковые модели.

Если права не указать при создании, ключ получит набор для картинок, видео, 3D, распознавания речи и чтения баланса. Чат, а с ним и Jev, нужно включать явно — чтобы случайный ключ не тратил деньги на длинные запросы.

Управление ключами из кода

Обычно ключи создают в интерфейсе, но это можно делать и программно — из сессии студии (обычная авторизация на сайте, не API-ключ).

ArcKep доступен как удалённый MCP-сервер через стандартный Streamable HTTP. Подключайте любой агент, который поддерживает этот протокол. Один адрес открывает модели, цены, баланс, загрузку файлов, генерацию картинок, видео и 3D, презентации, озвучку и распознавание речи, чат, решения Jev и пакетные запросы.

https://arckep.ru/api/v1/mcp

Как авторизоваться

Если агент принимает заголовки для MCP-сервера, создайте обычный ключ в Настройках → API и передайте Authorization: Bearer ark_live_…. Если агент предлагает вход через браузер, выберите OAuth: ArcKep покажет страницу согласования и создаст отдельный ключ для этого подключения. Его можно отозвать в Настройках → API.

Как проходит генерация

Агент может вызвать list_models, затем estimate_image, estimate_videoили estimate_3d. create_image, create_video и create_3d запускают платную задачу и возвращают её ID. Результат приходит через соответствующий get_*. В параметрах генерации доступен необязательный max_cost_rub.

Видео Higgsfield

Модели Higgsfield (идентификаторы higgsfield-…) в list_models значатся как видео, но запускаются отдельными инструментами: estimate_higgsfield_cinema и create_higgsfield_cinema для Cinema Studio 4.0, estimate_higgsfield_genjutsu и create_higgsfield_genjutsu (параметр kind: motion или swap) для Genjutsu; для «смены стиля» Genjutsu — list_higgsfield_restyle_styles (оттуда берутpreset_id), estimate_higgsfield_restyle и create_higgsfield_restyle; для Wan 3.0 Prime — estimate_higgsfield_wan_prime и create_higgsfield_wan_prime (режим выбирают файлы: кадры image_url / end_image_url или образцы image_urls, video_urls, audio_urls). Пока ролик стоит в очереди у провайдера, его можно отменить через cancel_higgsfield_video, деньги вернутся. Если отправить такую модель в create_video, агент получит подсказку, какой инструмент нужен. Картинки, видео и звук для ссылок загружает upload_media; при ошибке API агент видит её текст целиком.

Свои голоса озвучки

design_speech_voice создаёт голос по описанию, replicate_speech_voice клонирует его по двум WAV в base64 (source_audio_base64 — образец голоса, consent_audio_base64 — запись фразы согласия, каждая до 5 МиБ), delete_speech_voice удаляет свой голос. Всё бесплатно; фразы согласия агент найдёт в описании инструмента. На аккаунт — не больше 5 сохранённых голосов: шестой получит 409 VOICE_LIMIT_REACHED, место освобождает delete_speech_voice. Голос из list_my_speech_voices подставляется в create_speech как custom_voice_id. Подробности — в разделе «Озвучка текста».

Презентации

create_presentation запускает сборку презентации Claude и сразу возвращает её ID: это долгая задача на несколько минут. Агент опрашивает get_presentation, пока статус не станет awaiting_input, и отдаёт пользователю ссылки на PPTX, PDF и картинки слайдов (result.pptx_url, result.pdf_url, result.slides). Править готовую презентацию — revise_presentation, остановить ход — cancel_presentation, узнать типичную цену — estimate_presentation, перечислить свои — list_presentations. Вариант tier по умолчанию fast (Sonnet 5.5 с советником Opus 5.5), pro — Opus 5.5 на всю презентацию, дороже. Нужно право presentations:write или chat:write. Файл, которого нет в сети, сначала загружают через upload_media (документ PPTX, PDF, DOCX, XLSX, TXT, MD или CSV до 10 МБ) и подставляют полученный url в file_urls.

Документы

create_document запускает сборку документа Claude (format: docx — Word, xlsx — Excel с формулами, pdf) и сразу возвращает ID: это долгая задача на несколько минут. Агент опрашивает get_document, пока статус не станет awaiting_input, и отдаёт пользователю ссылки на файл и PDF-копию (result.file_url, result.pdf_url). Править готовый документ — revise_document, остановить ход — cancel_document, узнать типичную цену — estimate_document, перечислить свои — list_documents. Нужно право documents:write или chat:write; исходные файлы грузят так же, как для презентаций, через upload_media.

Карточки для маркетплейсов

create_marketplace_cards запускает сборку пачки карточек для Wildberries или Ozon по фото товара и его описанию и сразу возвращает номер: это долгая задача на 3–8 минут. Агент опрашивает get_marketplace_cards, пока статус не станет completed, и отдаёт пользователю картинки из output.images. Цену вилкой без запуска даёт estimate_marketplace_cards, готовые пачки — list_marketplace_cards. Нужно право images:write. Фото, которого нет в сети, сначала загружают через upload_media и подставляют полученный url в image_urls.

Список моделей задаётся на сервере и меняется. Не зашивайте названия из этой страницы в код — спрашивайте каталог у API. Это единственный достоверный источник: там же приходят поддерживаемые пропорции, разрешения, длительности и цены.

curl -sS -H "Authorization: Bearer $ARK_KEY" \
  https://arckep.ru/api/v1/models

Каждая запись имеет поле type: image, video, model3d, stt (распознавание речи), tts (озвучка), chat или decision. Оно говорит, в какой раздел API её отправлять.

Поля generation_endpoint и estimate_endpoint содержат маршруты запуска и оценки относительно /api/v1. Используйте их, чтобы выбрать нужную операцию, включая специальные режимы видео. Если отдельной оценки нет, придёт null.

{
  "object": "list",
  "data": [
    {
      "id": "gemini-3.1-flash-image",
      "type": "image",
      "modes": ["generate", "edit_with_reference"],
      "aspect_ratios": ["1:1", "16:9", "9:16"],
      "resolutions": ["1K", "2K", "4K"],
      "max_images": 1,
      "supports_thinking": true
    },
    {
      "id": "wan3.0-t2v",
      "type": "video",
      "name": "Wan 3.0 (T2V)",
      "modes": ["t2v"],
      "max_duration": 30,
      "pricing_hint": "… ₽/с"
    },
    {
      "id": "hunyuan-3d-3.1",
      "type": "model3d",
      "name": "Hunyuan 3D 3.1",
      "modes": ["text_to_3d", "image_to_3d"],
      "quality_levels": ["fast", "medium", "quality", "max", "ultra"],
      "pricing_hint": "при запуске держим максимум для настроек: от 57,50 до 77,63 ₽, лишнее вернём"
    },
    {
      "id": "gemini-3.5-transcribe",
      "type": "stt",
      "name": "Gemini 3.5 Transcribe",
      "modes": ["transcription"],
      "max_duration": 1800,
      "max_file_mb": 45,
      "capabilities": ["language_detection", "diarization", "word_timestamps"],
      "pricing_rub_per_minute": 0.5865
    },
    {
      "id": "z-ai/glm-5.3",
      "type": "chat",
      "context_window": 1000000,
      "capabilities": ["function_calling", "streaming", "reasoning"],
      "pricing_rub_per_1m": { "input": 169.4, "output": 532.4 }
    }
  ]
}

Показывает тот же остаток, что и в личном кабинете. Если вы состоите в организации и она активна, вернётся баланс организации — с него же и списывается.

{
  "balance_rub": "150.00",
  "is_corporate": false,
  "corporate_name": null
}

Суммы всюду приходят строками, а не числами. Это сделано намеренно: дробные рубли в формате JSON-числа теряют точность при округлении. Разбирайте их как десятичные, а не как float.

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

curl -sS -X POST https://arckep.ru/api/v1/uploads \
  -H "Authorization: Bearer $ARK_KEY" \
  -F "file=@./reference.png"

{
  "key": "images/42/9f3c….png",
  "url": "https://…подписанная-ссылка…"
}

Генерация асинхронная. Запрос возвращает 202 и номер задачи сразу — картинки ещё нет. Готовый результат забирают опросом статуса или через вебхук.

Создание

curl -sS -X POST https://arckep.ru/api/v1/images/generations \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "предметная съёмка керамической кружки, мягкий студийный свет",
    "n": 2,
    "size": "1024x1024",
    "quality": "low"
  }'

С опорным изображением

Некоторые модели умеют редактировать присланную картинку или держать один и тот же объект на разных кадрах. Для них передайте ссылки в reference_image_urls.

curl -sS -X POST https://arckep.ru/api/v1/images/generations \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "тот же объект, снаружи, закатный свет",
    "reference_image_urls": ["https://…ссылка-из-uploads…"],
    "webhook_url": "https://hooks.example.com/arckep"
  }'

FLUX 3 Image Klein, FLUX 3 Image и Krea 3

• Размер (resolution): у FLUX 3 — 768sq, 1k, 1.5k, 2k, 4k (можно писать и 1K, 4K); у Krea 3 — 1K или 2K. За запрос одна картинка. Исходных фото: до 10 у FLUX 3, до 6 у Krea 3.
• Цена FLUX 3 зависит только от размера, число фото на неё не влияет. Цена Krea 3 — размер, надбавка за thinking: true («продумать правку», работает дольше) и размер каждого вашего фото (около 2,30 ₽ за мегапиксель).
• aspect_ratio: "auto" понимают все три модели. У FLUX 3 при правке кадр точно как у вашего первого фото: вертикальное фото вернётся вертикальным. У Krea 3 кадр подбирает сама модель по вашему фото; на вертикальных фото это пока не замерено. Чтобы получить другой кадр, укажите пропорции явно.
• Krea 3 с фото: расчёт /images/estimate — верхняя граница (cost_is_upper_bound: true), на каждое фото закладывается до 5,75 ₽ (фото 2,5 Мп; большие уменьшаются перед отправкой). Спишется по настоящему размеру ваших фото, разница вернётся — итог не бывает выше расчёта.
• Только у Krea 3: thinking: true — «продумать правку» (работает дольше, фиксированная надбавка), а regional_edit: true — «менять только нужное»: модель правит то, что названо в описании, и не трогает остальное на фото. Для regional_edit нужно хотя бы одно фото; поставщик называет режим пробным, он работает дольше, цену не меняет. У другой модели или без фото запрос отклоняется ошибкой 400/422 до списания денег. Расчёт /images/estimate принимает то же поле и для такого сочетания отвечает allowed: false.
• Результат Klein в 4k приходит в PNG и весит около 30 МБ (замер: 5024×3344 — 33,7 МБ). Учтите это при загрузке и хранении.

Krea 3 Ultra

• krea-3-ultra — отдельная модель, не режим krea-3. Она только правит и собирает кадр по фото: в reference_image_urls нужно от 1 до 8 ссылок, а запрос без фото отклоняется до списания денег. За запрос одна картинка (num_images — 1).
• Размер не выбирается: кадр всегда 2K, а формат выбирает сама модель. aspect_ratio и resolution можно не передавать; допустимы только "auto" и "2K", любое другое значение — ошибка INVALID_PARAMETER (400/422).
• Цена зависит только от числа фото (курс тот же, 115 ₽ за $), размер самих фото на неё не влияет: 1 фото — 37,52 ₽, 2 — 49,09 ₽, 3 — 60,66 ₽, 4 — 72,23 ₽, 5 — 83,80 ₽, 6 — 95,37 ₽, 7 — 106,94 ₽, 8 — 118,51 ₽. Расчёт /images/estimate совпадает со списанием.
• Нет negative_prompt, thinking и regional_edit: модель всегда работает в самом вдумчивом режиме. Эти поля отклоняются ошибкой до списания денег (у krea-3 они есть).
• Работает дольше остальных: до нескольких минут, бывает около 10. Для таких задач удобен webhook_url.

Статус и результат

curl -sS -H "Authorization: Bearer $ARK_KEY" \
  https://arckep.ru/api/v1/images/generations/123

{
  "id": 123,
  "object": "image.generation",
  "status": "completed",
  "model": "gemini-3.1-flash-image",
  "created_at": "2026-07-27T12:00:00+00:00",
  "completed_at": "2026-07-27T12:00:24+00:00",
  "cost_rub": "4.24",
  "charged_from": "personal",
  "error": null,
  "output": {
    "images": [
      { "url": "https://arckep.ru/…", "expires_in": null },
      { "url": "https://…подписанная…", "expires_in": 86400 }
    ]
  }
}

Поле output заполняется только у завершённых задач. У части ссылок есть expires_in — срок жизни в секундах, примерно сутки. Если ссылка протухла, запросите статус задачи ещё раз и получите свежую.

Сколько будет стоить

Цену можно узнать заранее, ничего не запуская и не списывая. Считается тем же механизмом, что и реальное списание. В ответе: допустимо ли сочетание настроек, точная цена или верхняя граница. При создании можно передать max_cost_rub — если оценка выше, задача не стартует.

curl -sS -X POST https://arckep.ru/api/v1/images/estimate \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.1-flash-image", "num_images": 1, "resolution": "1K"}'

Если вам назначена личная скидка, в расчёте и в объекте задачи рядом с cost_rub (то, что будет списано) лежат list_cost_rub — прайс — и discount_pct — процент вашей скидки; без скидки list_cost_rub пустой, а discount_pct равен 0.

{
  "model": "gemini-3.1-flash-image",
  "cost_rub": "3.39",
  "list_cost_rub": "4.24",
  "discount_pct": 20,
  "currency": "RUB",
  "allowed": true,
  "cost_is_upper_bound": false
}

Список своих задач

Возвращает задачи этого аккаунта: и из API, и из веб-студии. В поле source будет studio или api. Чужие задачи не видны.

curl -sS -H "Authorization: Bearer $ARK_KEY" \
  "https://arckep.ru/api/v1/images/generations?limit=20"

Для листания передавайте before_id — номер самой старой задачи из предыдущей страницы. Признак has_more подскажет, есть ли ещё.

Устроено так же, как картинки: запрос возвращается сразу с номером задачи, готовый ролик появляется позже. Разница в сроках — видео считается от десятков секунд до десятков минут, а у тяжёлых моделей дольше.

Режимы

Не каждая модель умеет всё. Доступные режимы конкретной модели перечислены в каталоге в поле modes. Если модель называется с окончанием -i2v, она работает только от картинки, и текстовый режим для неё вернёт ошибку.

Файлы, которые модель не использует, мы не принимаем молча: последний кадр там, где его нет, опорное видео модели без референсов, исходный ролик для модели, которая не правит видео, — это ответ 400 INVALID_PARAMETER до списания денег. Что принимает каждая модель:

У Kling 3.0 качество задаётся полем resolution: 720p — стандарт, 1080p — pro, 4k — 4K (у V3 и Omni). У Kling 2.6 Pro и O1 ставка одна. Допустимые длительности: Kling 2.6 Pro — 5 или 10 секунд, O1 — от 3 до 10, Kling 3.0 — от 3 до 15 (у 3.0 O1 — 5 или 10), FLUX 3 — от 5 до 20. auto_duration для них не принимается.

Создание

curl -sS -X POST https://arckep.ru/api/v1/videos/generations \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "wan3.0-t2v",
    "prompt": "кинематографичный облёт дроном над туманными горами",
    "mode": "t2v",
    "duration_seconds": 5,
    "aspect_ratio": "16:9",
    "with_audio": true
  }'

curl -sS -X POST https://arckep.ru/api/v1/videos/generations \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-i2v",
    "prompt": "медленный наезд камеры, естественное движение",
    "mode": "i2v",
    "image_url": "https://…ссылка-из-uploads…",
    "duration_seconds": 5
  }'

Grok Imagine Video 1.5 Lite

grok-imagine-video-1.5-lite: текст или одно стартовое фото, от 1 до 15 секунд. Для текста доступны также форматы 21:9 и 5:2; при генерации из фото пропорции берутся из исходника. Разрешения: 480p по умолчанию, 720p и 1080p через апскейл из 720p. Звук включён по умолчанию; with_audio: false создаёт беззвучный ролик за ту же цену. Референсы, голоса, последний кадр, правка и продление у Lite не поддерживаются. Актуальные ставки по разрешениям — в GET /api/v1/models, расчёт — POST /api/v1/videos/estimate.

Автоматическая длительность

У части моделей длительность выбирает сама модель. Для таких запросов передайте auto_duration. Резервируется максимальная длительность, а после готовности лишнее возвращается — вы платите за фактический хронометраж.

Seedance 2.0 Mini и Fast

Это более дешёвые версии Seedance 2.0: seedance-2.0-mini и seedance-2.0-fast. Режимов три — t2v, i2v и r2v. Всё, чего версия не умеет, мы отклоняем сразу ответом 400, до списания денег.

1080p и 4K есть только у полного seedance-2.0. Режим edit — это исходный ролик в video_url: он уходит первым опорным видео, а в prompt вы описываете, что с ним сделать (ролик в тексте — @Video1). Так же работает полный seedance-2.0. Звук на цену не влияет.

curl -sS -X POST https://arckep.ru/api/v1/videos/estimate \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-mini",
    "duration_seconds": 5,
    "resolution": "720p",
    "has_reference_videos": true
  }'

Если среди опорных файлов есть видео, оплачиваются секунды и входного ролика, и готового, по сниженной ставке. Сколько секунд в вашем ролике, мы узнаём только после загрузки, поэтому при постановке задачи резервируем верхнюю границу: на вход берём 15 секунд. Такой расчёт приходит с cost_is_upper_bound: true. Когда видео готово, мы считаем по фактической длине входного и выходного роликов и возвращаем разницу на баланс. Без опорного видео цена в расчёте — точная. Ставки в рублях за секунду для каждого разрешения лежат в поле pricing_hint каталога.

Статус и результат

{
  "id": 456,
  "object": "video.generation",
  "status": "completed",
  "model": "wan3.0-t2v",
  "cost_rub": "25.00",
  "charged_from": "personal",
  "error": null,
  "output": {
    "video_url": "https://…подписанная…",
    "thumbnail_url": "https://…подписанная…",
    "duration_seconds": 5
  }
}

Статус берётся из нашей базы: мы сами опрашиваем провайдера в фоне, вам не нужно держать соединение или повторять запрос к нему. Ссылки на видео и превью — временные, примерно на сутки; за свежими просто запросите задачу снова.

Предварительный расчёт цены — POST /api/v1/videos/estimate с моделью, длительностью, разрешением и признаком звука. Список своих задач и листание работают так же, как у картинок.

Если вам назначена личная скидка, в расчёте и в объекте задачи рядом с cost_rub (то, что будет списано) лежат list_cost_rub — прайс — и discount_pct — процент вашей скидки; без скидки list_cost_rub пустой, а discount_pct равен 0.

{
  "model": "wan3.0-t2v",
  "cost_rub": "20.00",
  "list_cost_rub": "25.00",
  "discount_pct": 20,
  "currency": "RUB",
  "allowed": true,
  "cost_is_upper_bound": false
}

Higgsfield: Cinema Studio 4.0, Genjutsu и Wan 3.0 Prime

Модели Higgsfield (higgsfield-cinema-4, higgsfield-genjutsu-motion, higgsfield-genjutsu-swap, higgsfield-genjutsu-restyle, higgsfield-wan-3-prime) показаны в GET /api/v1/models как видео, но POST /api/v1/videos/generations их не принимает и отвечает 400 с кодом INVALID_MODEL. Они запускаются своими путями, чтобы передать все настройки камеры, референсы и измерить стоимость входного видео. Нужен тот же ключ с правом videos:write.

Порядок такой: сначала estimate, затем generate с теми же полями и max_cost_rub из ответа. Если живая цена окажется выше, запуск вернёт 400 и ничего не спишет. Статус и готовый файл доступны через GET /api/v1/videos/generations/ID, а при указанном webhook_url по завершении придёт событие video.generation.completed или video.generation.failed. Для безопасных повторов отправляйте заголовок Idempotency-Key. Неизвестные поля отклоняются с ошибкой 422; в оценке те же поля, включая max_cost_rub и webhook_url, можно оставить, их там игнорируют.

Полный список допустимых значений стиля, камеры и палитры (их несколько десятков) — в руководстве /docs/api.md, раздел 10.6; неверное значение вернёт ошибку 422 с названием поля.

«Смена стиля» перерисовывает весь исходный ролик в выбранном стиле, а движение, камера и звук остаются. Длина и формат кадра берутся из ролика, цена считается по длине исходника и от стиля не зависит. Список стилей отдаёт Higgsfield (20 на 6 октября 2026), мы держим его в памяти час; стиль, которого у Higgsfield уже нет, отклоняется до списания.

Wan 3.0 Prime одним запросом умеет три режима, и какой из них, решают файлы: без файлов — по описанию, image_url (с необязательным end_image_url) — из фото, image_urls, video_urls и audio_urls — по образцам. Кадры и образцы вместе не принимаются (422). Цена считается за секунду готового ролика и зависит только от длины и разрешения: у провайдера $0,068, $0,14 и $0,28 в секунду для 480p, 720p и 1080p, по курсу студии 7,82, 16,10 и 32,20 ₽ в секунду на 10 октября 2026. Звук, обдумывание, формат кадра и файлы-образцы цену не меняют. Если живая цена провайдера когда-нибудь окажется выше этих ставок, запуск остановится до списания. Образец-ролик короче секунды, ролики или звуки длиннее 30 секунд вместе и звук не в WAV или MP3 отклоняются с кодом 400 до списания. Документ и страницу сайта как образец (file_url, link_url) провайдер принимает, а мы пока нет.

Для замены объекта (swap) в кадре исходника должно быть не меньше 409 600 пикселей, например 640×640. Слишком короткий или мелкий исходник отклоняется ещё до списания.

Каждая ссылка на медиа — публичный адрес https:// либо key или url, которые вернул POST /api/v1/uploads. Загрузка принимает картинки, видео mp4 и webm и звук mp3, wav, m4a и aac до 10 МБ; тип проверяется по содержимому, а не по заголовку. Чужие файлы и адреса внутренней сети отклоняются. В агентах для всего этого есть отдельные инструменты MCP (см. раздел «MCP для AI-агентов»).

curl -sS -X POST https://arckep.ru/api/v1/higgsfield/cinema/estimate \
  -H "Authorization: Bearer $ARCKEP_API_KEY" -H 'Content-Type: application/json' \
  -d '{"prompt":"Кинематографический портрет в мягком свете","duration":5,"resolution":"720p","aspect_ratio":"16:9","generate_audio":true}'

Доступны Hunyuan 3D 3.1, Meshy 7.1, Tripo H3.1 и Rodin 2.5. Все возвращают асинхронную задачу; после завершения доступен GLB.

После статуса completed можно также скачать STL для 3D-печати. Экспорт конвертирует готовый GLB, без новой генерации и без дополнительного списания. Перед печатью проверьте размер и целостность сетки в слайсере.

Модели и источники

Meshy, Tripo и Rodin работают через fal. Для них POST /models3d/estimate показывает точное списание до запуска; при ошибке оно возвращается. Meshy 2k/4k, Tripo quad и отдельные инструменты remesh/retexture/segment пока не доступны.

Rodin: варианты, настройки и формат файла

Rodin принимает текст (prompt), одно фото (image_url) или от 1 до 5 фото (image_urls); нужно ровно одно. Цену задают только variant и high_pack: обычный вариант стоит 46 ₽, с текстурами 4K — 138 ₽, быстрый — 11,50 ₽. Уровень детализации, сетка, остальные переключатели и формат файла цену не меняют; итог известен до запуска.

curl -sS -X POST https://arckep.ru/api/v1/models3d/generations \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"rodin-v2.5","image_urls":["https://…1.png","https://…2.png","https://…3.png"],"high_pack":true}'

curl -sS -X POST https://arckep.ru/api/v1/models3d/generations \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"rodin-v2.5","prompt":"деревянный сундук","variant":"fast","output_format":"fbx"}'

Недопустимые сочетания (быстрый вариант с high_pack, is_micro без уровня Extreme-High, сетка, которой нет у выбранного уровня, high_pack с сеткой из квадов, формат вне списка) отклоняются с ошибкой 400 до списания денег. Остальные настройки Meshy и Tripo (texture, polycount, topology, риг и другие) Rodin не принимает. Если провайдер откажет по содержанию картинки или текста, списанная сумма вернётся. Быстрый вариант обычно готов примерно за минуту, обычный — за две-четыре.

Формат файла

Один запуск даёт один формат. Другой формат — это новая генерация и новая оплата: готовый результат в другой формат бесплатно не пересохранить. Исключение — STL для печати: его можно бесплатно получить из готовой GLB-модели через GET /models3d/generations/{id}/download/stl.

В готовой задаче output.format — формат, output.file_url и output.file_name — ссылка и имя файла (для OBJ это ZIP). output.glb_url заполнено только у GLB, а output.preview_url — картинка-превью, если провайдер её вернул. Результаты бывают большими: обычный GLB с текстурами 4K — около 65 МБ, быстрый — около 2 МБ. Ссылки живут сутки.

Hunyuan: что передать

Нужно ровно одно: либо описание, либо картинка. Оба сразу — ошибка. Картинку сначала загрузите через POST /uploads и подставьте ссылку из ответа.

Hunyuan: качество

Те же пять ступеней, что в студии на странице 3D. Можно передать короткое имя quality или точное число полигонов в face_count. Если заданы оба — берётся число. При запуске держим максимум для выбранных настроек (57,50–77,63 ₽); если итог получился меньше, разницу возвращаем.

Создание

curl -sS -X POST https://arckep.ru/api/v1/models3d/generations \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "hunyuan-3d-3.1",
    "prompt": "красная керамическая ваза, глазурь, студийный свет",
    "quality": "quality"
  }'

curl -sS -X POST https://arckep.ru/api/v1/models3d/generations \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hunyuan-3d-3.1",
    "image_url": "https://…ссылка-из-uploads…",
    "quality": "ultra",
    "enable_pbr": true
  }'

curl -sS -X POST https://arckep.ru/api/v1/models3d/generations \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"meshy-v7.1","image_urls":["https://…front.png","https://…side.png"],"texture":true,"enable_rigging":true}'

curl -sS -X POST https://arckep.ru/api/v1/models3d/generations \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"model":"tripo-h3.1","prompt":"ceramic vase","geometry_quality":"detailed","texture_quality":"standard"}'

Для Meshy, Tripo и Rodin дополнительно доступен image_urls: до 4 фото у Meshy и Tripo, до 5 у Rodin. Для Meshy/Tripo также texture, polycount, texture_quality, geometry_quality, topology, model_type, enable_rigging, enable_animation и animation_action_id. Сервер проверяет поля по выбранной модели; параметры Hunyuan quality, face_count и generate_type для них не применяются.

Статус и результат

curl -sS -H "Authorization: Bearer $ARK_KEY" \
  https://arckep.ru/api/v1/models3d/generations/123

{
  "id": 123,
  "object": "model3d.generation",
  "status": "completed",
  "model": "hunyuan-3d-3.1",
  "cost_rub": "18.40",
  "charged_from": "personal",
  "source": "api",
  "output": {
    "glb_url": "https://…подписанная…",
    "format": "glb",
    "file_url": "https://…подписанная…",
    "file_name": "model-123.glb",
    "preview_url": null,
    "file_size_bytes": 1843200,
    "face_count": 500000,
    "generate_type": "Normal",
    "enable_pbr": false
  }
}

Когда статус completed, в output.glb_url лежит ссылка на файл. Ссылка живёт сутки — скачайте или запросите статус ещё раз, чтобы получить свежую.

curl -sS -L -H "Authorization: Bearer $ARK_KEY" \
  -o model-123.stl \
  https://arckep.ru/api/v1/models3d/generations/123/download/stl

Сколько будет стоить

Расчёт ничего не списывает. Для Hunyuan cost_rub — верхняя граница, и именно её мы держим при запуске: details.deposit_rub равен cost_rub. Для Meshy, Tripo и Rodin обе суммы равны точной цене выбранных настроек.

Если вам назначена личная скидка, cost_rub (и details.deposit_rub) — то, что будет списано, а list_cost_rub — прайс и discount_pct — процент вашей скидки; те же два поля есть в объекте задачи. Без скидки list_cost_rub пустой, а discount_pct равен 0.

{
  "model": "rodin-v2.5",
  "cost_rub": "36.80",
  "list_cost_rub": "46.00",
  "discount_pct": 20,
  "currency": "RUB",
  "allowed": true,
  "cost_is_upper_bound": true,
  "details": { "deposit_rub": "36.80" }
}

curl -sS -X POST https://arckep.ru/api/v1/models3d/estimate \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "hunyuan-3d-3.1", "prompt": "ваза", "quality": "ultra"}'

Список своих задач

Как у картинок: свои задачи из API и из студии, поле source — studio или api.

curl -sS -H "Authorization: Bearer $ARK_KEY" \
  "https://arckep.ru/api/v1/models3d/generations?limit=20"

Gemini Flash TTS и Flash Lite TTS превращают текст в речь. Отправьте текст, модель и голос — в ответе придёт ссылка на готовый WAV-файл. Доступные модели имеют тип tts в каталоге.

curl -sS https://arckep.ru/api/v1/audio/speech \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: speech-example-1" \
  -d '{"model":"gemini-3.8-flash-tts","text":"Привет, мир!","voice_id":"Kore","style":"warm and calm"}'

До 6000 символов. style задаёт подачу речи. Для диалога передайте second_voice_id и массив turns: у каждой реплики есть speaker (A или B), text и необязательный style. Для своего голоса укажите custom_voice_id из списка ваших голосов; диалоги используют два обычных голоса.

Оценка принимает model и text; для диалога объедините тексты реплик. Итоговая стоимость в cost_rub зависит от фактических токенов текста и аудио. При повторе после таймаута используйте тот же Idempotency-Key. Нужен доступ audio:write или chat:write.

Если вам назначена личная скидка, cost_rub в оценке — то, что будет списано, а list_cost_rub — прайс и discount_pct — процент вашей скидки; без скидки list_cost_rub пустой, а discount_pct равен 0.

{
  "model": "gemini-3.8-flash-tts",
  "cost_rub": "0.80",
  "list_cost_rub": "1.00",
  "discount_pct": 20,
  "currency": "RUB",
  "cost_is_upper_bound": false,
  "details": { "approximate": true, "billing_unit": "token", "output_format": "wav" }
}

Свои голоса: создать, клонировать, удалить

Создание, клонирование и удаление голоса бесплатны и не попадают в историю озвучки. Голоса из API и из студии лежат в одном списке GET /audio/voices/mine. Передайте idголоса как custom_voice_id в POST /audio/speech — он работает с обеими моделями озвучки. Нужен доступ audio:write или chat:write.

Голос по описанию. Тело запроса — JSON: display_name (1–120 символов), prompt (10–1000 символов: возраст, тембр, темп, манера, акцент), gender (male, female или neutral) и необязательный language_code (по умолчанию ru-RU, например en-US). Поля model_id здесь нет: лишнее поле вернёт 422. В ответе (201) — voice с полями id, display_name, kind, language_code, expires_at, stored и короткий образец звучания в sample_audio_base64. Голос хранится 365 дней.

curl -sS https://arckep.ru/api/v1/audio/voices/design   -H "Authorization: Bearer $ARK_KEY" -H "Content-Type: application/json"   -d '{"display_name":"Диктор","prompt":"Тёплый баритон, спокойный темп, дружелюбная манера","gender":"male","language_code":"ru-RU"}'

Клон по записи. Запрос multipart с полями: source_audio — образец голоса, consent_audio — отдельная запись, где тот же человек читает фразу согласия, display_name (1–120 символов), consent_confirmed=true (вы подтверждаете, что владелец голоса согласен; без него придёт 400) и необязательный store. Оба файла — WAV, 24 кГц, моно, 16 бит, до 5 МБ каждый; образец от 10 до 30 секунд, запись согласия от 2 до 30 секунд. Формат проверяется до обращения к Google, ошибка называет файл в details.field. По умолчанию store=true: голос хранится 365 дней и занимает одно место в проекте Google; store=false даёт временный ключ на 7 дней без места.

curl -sS https://arckep.ru/api/v1/audio/voices/replicate   -H "Authorization: Bearer $ARK_KEY"   -F source_audio=@sample.wav -F consent_audio=@consent.wav   -F display_name="Мой голос" -F consent_confirmed=true

Удаление. DELETE /audio/voices/{voice_id} с локальным id из GET /audio/voices/mine отвечает 200 и {"message":"Deleted"}. Чужой или несуществующий голос — 404 RESOURCE_NOT_FOUND. Сохранённый голос удаляется и у Google, место в проекте освобождается; если Google не ответил, голос остаётся и удаление можно повторить.

• На аккаунт — не больше 5 сохранённых голосов. Считаются неистёкшие голоса, которые хранятся у Google, откуда бы они ни появились: из студии или из API; истёкшие и временные ключи (store=false) не считаются. Шестой голос отклоняется ещё до обращения к Google: 409 VOICE_LIMIT_REACHED и details {"limit": 5, "used": 5}. Место освобождает DELETE /audio/voices/{voice_id}. Тот же лимит действует в студии, в API и в MCP; число приходит в поле saved_limit ответа GET /audio/voices/mine. Параллельное создание того же аккаунта получит 429 VOICE_CREATION_IN_PROGRESS — повторите чуть позже.
• Отдельно действует лимит Google — 200 сохранённых голосов на весь проект ArcKep (все пользователи, студия и API вместе). При его исчерпании создание и клон с store=true тоже отвечают 409 VOICE_LIMIT_REACHED, но без details.
• Ошибки формата, длины и размера записи, пустое имя или описание, неверный language_code и неподтверждённое согласие — 400 VALIDATION_ERROR; слишком короткое описание или лишнее поле — 422.
• Заголовок Idempotency-Key для этих маршрутов не работает. Если запрос оборвался по таймауту или соединение разорвалось, голос мог уже создаться: откройте GET /audio/voices/mine перед повтором и удалите лишний голос через DELETE.
• Служебные ключи Google в ответах и журналах не появляются, только ваш id голоса.

В MCP доступны estimate_speech, create_speech, list_speech, get_speech, list_speech_voices, list_my_speech_voices, design_speech_voice, replicate_speech_voice и delete_speech_voice. Инструмент create_speech требует idempotency_key и возвращает готовый результат. replicate_speech_voice принимает записи в base64: source_audio_base64 и consent_audio_base64, каждая до 5 МиБ, плюс request с display_name, consent_confirmed и store. Фразы согласия и лимиты есть в описании инструмента, ошибки лимита агент получает как есть. У инструментов голосов idempotency_key нет.

Присылаете запись — в том же ответе получаете текст. Задачи и опроса статуса здесь нет: запрос висит, пока идёт распознавание, и возвращается уже с результатом. Работает модель gemini-3.5-transcribe от Google. Список доступных моделей всегда в каталоге: у распознавания речи в нём тип stt.

Запрос

curl -sS -X POST https://arckep.ru/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F model=gemini-3.5-transcribe \
  -F language=ru \
  -F diarize=true \
  -F file=@./meeting.mp3

Разметка спикеров и таймкоды вместе работают. Метки спикеров у Gemini вида spk_1, spk_2.

{
  "id": "tr_3f9c1d2a8e4b4c7e9a0b1c2d",
  "object": "transcription",
  "model": "gemini-3.5-transcribe",
  "text": "Здравствуйте. Добрый день.",
  "language": "ru-RU",
  "duration_seconds": 125.4,
  "cost_rub": "1.23",
  "currency": "RUB",
  "speakers": ["spk_1", "spk_2"],
  "segments": [
    { "speaker": "spk_1", "text": "Здравствуйте.", "start": 0.1, "end": 0.9 },
    { "speaker": "spk_2", "text": "Добрый день.", "start": 1.2, "end": 1.9 }
  ]
}

В duration_seconds длина записи, которую измерили мы, а не та, что назвал клиент. Поле language — то, что вернул поставщик. Gemini язык не сообщает, поэтому там придёт ваша подсказка или null.

Что можно присылать

Большой файл не страшен: Gemini принимает до 13 МБ на запрос, поэтому всё, что больше, мы сначала сжимаем до речевого mp3 (моно, 16 кГц, 32 кбит/с) — для получасовой записи это несколько секунд, а длина и цена не меняются. Длиннее 30 минут — режьте на части. Если запись не подходит, получите ошибку AUDIO_TOO_LONG, FILE_TOO_LARGE или INVALID_FILE_TYPE ещё до обращения к поставщику, и деньги не списываются.

Сколько это стоит

• Сумма округляется вверх до копейки. Точное число за минуту — в каталоге, поле pricing_rub_per_minute.
• Цену под вашу запись покажет POST /audio/transcriptions/estimate — передайте model и duration_seconds. Это оценка самого Google; итог считается по фактическим токенам, так что плотная речь, разметка спикеров и таймкоды могут стоить дороже.
• Деньги списываются после того, как текст получен. Если поставщик не ответил или не принял запись — ничего не спишется.
• Перед запросом на балансе должна быть как минимум оценка (с запасом). Пока идёт распознавание, эта сумма на балансе придержана, и параллельные запросы не уведут счёт в минус.

Повторы и параллельные запросы

Через MCP используйте estimate_transcription и create_transcription. Передайте файл в content_base64, его filename, параметры в request и постоянный idempotency_key. Лимит MCP — 10 МиБ; для больших записей используйте HTTP API.

Если запрос оборвался по таймауту, не повторяйте его без заголовка Idempotency-Key: это второй платный вызов. С ключом повтор в течение суток вернёт тот же текст и ничего не спишет. Одновременных запросов на ключ — те же 10, что и у чата: счётчик общий с чатом и решениями Jev.

Claude собирает презентацию по вашему брифу: редактируемый PPTX, PDF, картинки слайдов и «карту презентации» (цель, аудитория, тема, план слайдов). Это долгая задача — несколько минут. Запрос сразу отвечает 202 с номером, дальше вы опрашиваете состояние. Правки — отдельными сообщениями в ту же презентацию. Нужен ключ с правом presentations:write или chat:write.

Запуск

curl -sS -X POST https://arckep.ru/api/v1/presentations \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "brief": "Коммерческое предложение для сети кофеен: обучение бариста, 8–10 слайдов, цены, кейс, следующий шаг",
    "tier": "fast",
    "file_urls": ["https://…образец.pptx"]
  }'

Ссылки в file_urls должны быть публичными, по HTTPS: сервер скачивает файлы сам. Адреса во внутренние сети и перенаправления на них отклоняются. Образец передают так же, как любой исходник: приложите свой PPTX или PDF и напишите в брифе «сделай в таком стиле». Повторите запрос с тем же Idempotency-Key после обрыва, и вторая презентация не запустится.

Свой файл без публичной ссылки

Если файл лежит у вас и выложить его нигде нельзя, загрузите его к нам и подставьте полученную ссылку в file_urls: и при создании, и в правке. Подходят PPTX, PDF, DOCX, XLSX, TXT, MD и CSV до 25 МБ; проверки те же, что при создании презентации. Нужен ключ с правом presentations:write, chat:write или uploads:write. Загрузка бесплатна, ссылка живёт около суток, поэтому запускайте презентацию сразу после загрузки.

UP=$(curl -sS -X POST https://arckep.ru/api/v1/uploads \
  -H "Authorization: Bearer $ARK_KEY" \
  -F "file=@./price.xlsx")
URL=$(echo "$UP" | jq -r .url)

curl -sS -X POST https://arckep.ru/api/v1/presentations \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"brief\": \"Отчёт по ценам: 6 слайдов, выводы вверху\", \"file_urls\": [\"$URL\"]}"

В ответе загрузки есть поле filename: под этим именем агент увидит файл. В имени остаются латинские буквы, цифры, _ и -; имя только из кириллицы превратится в file.pdf. Если в брифе вы ссылаетесь на файл по имени, называйте файлы латиницей.

{
  "id": 41,
  "object": "presentation",
  "status": "running",
  "tier": "fast",
  "title": "Коммерческое предложение для сети кофеен",
  "checks_done": 0,
  "max_checks": 3,
  "cost_usd": "0",
  "cost_rub": "0",
  "result": null
}

Состояние и файлы

curl -sS -H "Authorization: Bearer $ARK_KEY" \
  https://arckep.ru/api/v1/presentations/41

{
  "id": 41,
  "object": "presentation",
  "status": "awaiting_input",
  "tier": "fast",
  "checks_done": 2,
  "max_checks": 3,
  "check_result": "satisfied",
  "cost_usd": "0.8312",
  "cost_rub": "91.43",
  "images_count": 3,
  "images_cost_rub": "10.68",
  "last_agent_message": "Презентация готова: 9 слайдов, тема «Кофейня».",
  "result": {
    "version": 1,
    "pptx_url": "https://media.arckep.ru/m/…/deck.pptx?exp=…&sig=…",
    "pdf_url": "https://media.arckep.ru/m/…/deck.pdf?exp=…&sig=…",
    "slides": [
      { "n": 1, "title": "Бариста за две недели", "image_url": "https://media.arckep.ru/m/…/slide-01.png?…" }
    ],
    "deck": { "goal": "…", "audience": "…", "theme": "…", "slides": [] },
    "changelog": "Первая версия презентации."
  }
}

В result всегда последняя выданная версия. Пока идёт правка, статус running, а result — предыдущая версия. Ссылки подписаны и живут около суток: запросите карточку ещё раз, чтобы получить свежие. result.deck — карта презентации: по ней можно пересобрать презентацию или показать план слайдов. Список ваших презентаций — GET /presentations (поля limit до 100 и before_id).

Правки и остановка

curl -sS -X POST https://arckep.ru/api/v1/presentations/41/messages \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Сделай третий слайд короче и поставь наш логотип", "file_urls": ["https://…logo.png"]}'

Сообщение — это и правка, и вопрос: агент решает по тексту. На вопрос или обсуждение он ответит (last_agent_message) и обновит карту презентации, а презентацию пересоберёт, только когда вы попросите; тогда в result появится новая версия. Проверки качества считаются заново для каждого сообщения. Ответ 202, дальше тот же опрос. Пока агент работает, новое сообщение не принимается: 409 — дождитесь awaiting_input. POST /presentations/41/cancel останавливает текущий ход; презентация остаётся, и после остановки можно писать дальше.

Сколько стоит

Цена — по фактическому расходу: настоящая стоимость сессии Claude в долларах по прайсу Anthropic, умноженная на курс чата (110 ₽ за доллар), с вашей скидкой, если она есть. Фиксированной цены за презентацию нет, каждая правка добавляется к той же презентации. Потолка на сессию нет: презентация доделывается до результата. Деньги списываются в конце каждого хода агента; ход, который закончился ошибкой без результата, возвращается. Поле cost_usd — расход сессии, cost_rub — сколько списано с баланса.

Картинки для слайдов агент делает своим инструментом generate_image, когда бриф просит иллюстрации (Nano Banana 2.1 от Google, по прайсу около 5 ₽ за картинку, не больше 10 на презентацию). Каждая картинка списывается с вашего баланса как обычная генерация, как только готова (не получилась — возврат). Если денег на картинку нет, агент продолжает без неё. В cost_rub презентации эти списания не входят: в карточке они отдельно, в полях images_count и images_cost_rub.

Начать презентацию и отправить сообщение можно, пока на балансе (личном или организации) не меньше порога min_balance_rub: это бо́льшая из 30 ₽ и типичной стоимости варианта, умноженная на «1 + число ваших презентаций, которые уже идут». Иначе 402 INSUFFICIENT_BALANCE с полями details.required и details.available, и ничего не запускается. Уже начатый ход доделывается и списывается целиком, даже если баланс уйдёт в минус: долг гасится пополнением.

curl -sS -X POST -H "Authorization: Bearer $ARK_KEY" \
  https://arckep.ru/api/v1/presentations/estimate

{
  "pricing": "actual",
  "rate_rub_per_usd": 110.0,
  "typical_cost_rub": { "fast": 84.5, "pro": null },
  "min_balance_rub": { "fast": 85, "pro": 30 },
  "currency": "RUB",
  "window_days": 30
}

typical_cost_rub — медиана итоговой стоимости презентаций, готовых за последние 30 дней, отдельно для каждого варианта (по прайсу, до вашей скидки). Пока готовых презентаций меньше трёх, вместо числа стоит null.

Для MCP-агентов

Те же операции доступны инструментами estimate_presentation, create_presentation, get_presentation, list_presentations, revise_presentation и cancel_presentation. create_presentation отвечает сразу и добавляет подсказку для пользователя; результат агент забирает через get_presentation и отдаёт пользователю ссылки на PPTX, PDF и картинки слайдов.

Claude делает документ по вашему заданию: Word (docx), таблицу Excel с настоящими формулами (xlsx) или PDF. К файлу прилагаются PDF-копия для просмотра (если получилось), картинка первой страницы и краткая сводка. Работает тот же механизм, что у презентаций: запрос сразу отвечает 202 с номером, дальше вы опрашиваете состояние; правки — отдельными сообщениями в тот же документ. Нужен ключ с правом documents:write или chat:write.

Запуск

curl -sS -X POST https://arckep.ru/api/v1/documents \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "format": "xlsx",
    "brief": "Смета на ремонт кухни 12 м²: материалы, работы, итог с НДС; цены возьми из прайса",
    "tier": "fast",
    "file_urls": ["https://…price.xlsx"]
  }'

Ссылки в file_urls должны быть публичными, по HTTPS: сервер скачивает файлы сам. Адреса во внутренние сети и перенаправления на них отклоняются. Повторите запрос с тем же Idempotency-Key после обрыва, и второй документ не запустится.

Свой файл без публичной ссылки

Загрузите файл через POST /api/v1/uploads и подставьте полученную ссылку в file_urls: и при создании, и в правке. Подходят PPTX, PDF, DOCX, XLSX, TXT, MD и CSV до 25 МБ. Нужен ключ с правом documents:write, chat:write или uploads:write. Загрузка бесплатна, ссылка живёт около суток.

{
  "id": 17,
  "object": "document",
  "format": "xlsx",
  "status": "running",
  "tier": "fast",
  "title": "Смета на ремонт кухни",
  "checks_done": 0,
  "max_checks": 3,
  "cost_usd": "0",
  "cost_rub": "0",
  "result": null
}

Состояние и файлы

curl -sS -H "Authorization: Bearer $ARK_KEY" \
  https://arckep.ru/api/v1/documents/17

{
  "id": 17,
  "object": "document",
  "format": "xlsx",
  "status": "awaiting_input",
  "tier": "fast",
  "checks_done": 2,
  "max_checks": 3,
  "check_result": "satisfied",
  "cost_usd": "0.4120",
  "cost_rub": "45.32",
  "last_agent_message": "Смета готова: 3 листа, итоги посчитаны формулами.",
  "result": {
    "version": 1,
    "file_url": "https://media.arckep.ru/m/…/workbook.xlsx?exp=…&sig=…",
    "pdf_url": "https://media.arckep.ru/m/…/workbook.pdf?exp=…&sig=…",
    "preview_url": "https://media.arckep.ru/m/…/preview.png?exp=…&sig=…",
    "summary": { "title": "Смета на ремонт кухни", "sheets": ["Данные", "Расчёт", "Итог"], "open_questions": [] },
    "changelog": "Первая версия."
  }
}

file_url — сам документ в выбранном формате. pdf_url — копия для просмотра в браузере: для Word и Excel она есть, если конвертация получилась; для формата pdf это тот же файл, что и file_url. preview_url — картинка первой страницы, когда агент смог её нарисовать, иначе null. summary — сводка агента: название, разделы или листы, допущения, открытые вопросы. В result всегда последняя выданная версия; пока идёт правка, статус running, а result — предыдущая версия. Ссылки подписаны и живут около суток: запросите карточку ещё раз, чтобы получить свежие. Список ваших документов — GET /documents (поля limit до 100 и before_id).

Правки и остановка

curl -sS -X POST https://arckep.ru/api/v1/documents/17/messages \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Добавь лист с доставкой и пересчитай итог формулой"}'

Сообщение — это и правка, и вопрос: агент решает по тексту. На вопрос он ответит (last_agent_message) и обновит сводку, а файл пересоберёт, только когда вы попросите; тогда в result появится новая версия. Ответ 202, дальше тот же опрос. Пока агент работает, новое сообщение не принимается: 409 — дождитесь awaiting_input. POST /documents/17/cancel останавливает текущий ход; документ остаётся, и после остановки можно писать дальше.

Сколько стоит

Цена — по фактическому расходу: настоящая стоимость сессии Claude в долларах по прайсу Anthropic, умноженная на курс чата (110 ₽ за доллар), с вашей скидкой, если она есть. Фиксированной цены нет, каждая правка добавляется к тому же документу. Деньги списываются в конце каждого хода агента; ход, который закончился ошибкой без результата, возвращается. В журнале баланса списание подписано, например «Документ Word №17».

Начать документ и отправить сообщение можно, пока на балансе (личном или организации) не меньше порога min_balance_rub: это бо́льшая из стартовой суммы и типичной стоимости варианта, умноженная на «1 + число ваших презентаций и документов, которые уже идут». Иначе 402 INSUFFICIENT_BALANCE с полями details.required и details.available, и ничего не запускается. Уже начатый ход доделывается и списывается целиком, даже если баланс уйдёт в минус: долг гасится пополнением.

curl -sS -X POST -H "Authorization: Bearer $ARK_KEY" \
  https://arckep.ru/api/v1/documents/estimate

Поля ответа те же, что у презентаций: typical_cost_rub — медиана стоимости готовых документов за последние 30 дней по вариантам (null, пока их меньше трёх) и min_balance_rub.

Ошибки

Коды раздела: DOCUMENT_NOT_FOUND (404: нет такого документа, он чужой или раздел выключен), DOCUMENT_INVALID_REQUEST (422), DOCUMENT_CONFLICT (409: агент ещё работает или документ нельзя править), DOCUMENTS_NOT_CONFIGURED (503), DOCUMENT_UPSTREAM_ERROR (502), а также общий INSUFFICIENT_BALANCE (402). Презентацию по этому адресу открыть нельзя, как и документ по адресу презентаций.

Для MCP-агентов

Те же операции доступны инструментами estimate_document, create_document, get_document, list_documents, revise_document и cancel_document. create_document отвечает сразу; результат агент забирает через get_document и отдаёт пользователю ссылки result.file_url и result.pdf_url. В чате студии помощник ждёт готовности сам.

Тот же инструмент, что раздел «Карточки МП» в студии, только из кода. Вы присылаете от одного до восьми фото товара и его описание. Сервис составляет план, рисует чистое фото товара и от 3 до 12 слайдов (обложка, преимущества, характеристики, детали) в формате площадки, 3:4 (900×1200), с учётом зон, где площадка рисует свои значки. Это долгая задача на 3–8 минут: запрос сразу отвечает 202 с номером, дальше вы опрашиваете состояние. Нужен ключ с правом images:write. Вебхуков и сообщений в Telegram для этих задач нет, только опрос.

Запуск

curl -sS -X POST https://arckep.ru/api/v1/marketplace-cards/generations \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "image_urls": ["https://…/headphones-1.jpg", "https://…/headphones-2.jpg"],
    "description": "Беспроводные полноразмерные наушники, Bluetooth 5.3, 40 часов работы, складной корпус",
    "title": "AUDIO Lux",
    "marketplace": "ozon"
  }'

Фото сервер скачивает сам, до ответа. Если ссылку взять не получилось, ответ 400 INVALID_PARAMETER с номером фото (саму ссылку мы не повторяем: подписанный адрес — секрет), и ничего не списывается. Адреса во внутренние сети и перенаправления на них отклоняются. Свой файл без публичной ссылки загрузите через POST /api/v1/uploads и подставьте полученную ссылку. Повторите запрос с тем же Idempotency-Key после обрыва, и вторая пачка не запустится. Задача занимает один из пяти одновременных слотов ключа, как картинка или видео.

{
  "id": "3f9c2a1b8d4e4f60a7b15c2d9e8f0a13",
  "object": "marketplace_card.generation",
  "status": "queued",
  "marketplace": "ozon",
  "product_title": "AUDIO Lux",
  "progress_pct": 0,
  "cost_rub": null,
  "output": null
}

Состояние и картинки

curl -sS -H "Authorization: Bearer $ARK_KEY" \
  https://arckep.ru/api/v1/marketplace-cards/generations/3f9c2a1b8d4e4f60a7b15c2d9e8f0a13

{
  "id": "3f9c2a1b8d4e4f60a7b15c2d9e8f0a13",
  "object": "marketplace_card.generation",
  "status": "completed",
  "marketplace": "ozon",
  "product_title": "AUDIO Lux",
  "progress_pct": 100,
  "n_slides": 4,
  "cost_rub": "41.82",
  "completed_at": "2026-10-22T10:19:48+00:00",
  "output": {
    "images": [
      { "index": 0, "role": "clean", "headline": "", "badges": [], "url": "https://media.arckep.ru/m/…?exp=…&sig=…", "expires_in": 86400 },
      { "index": 1, "role": "hero", "headline": "Звук без проводов", "badges": ["Bluetooth 5.3"], "url": "https://media.arckep.ru/m/…?exp=…&sig=…", "expires_in": 86400 }
    ],
    "product_summary": "Беспроводные полноразмерные наушники",
    "warnings": []
  }
}

В output.images все картинки по порядку. Первая, role: clean, это товар на чистом фоне. Дальше слайды: hero — обложка, затем benefits, specs, detail, usage, lifestyle, kit. headline и badges — текст на слайде. Ссылки подписаны и живут около суток (expires_in в секундах): запросите карточку ещё раз, чтобы получить свежие. В output.warnings бывают коды cover_qa_failed и slide_qa_failed:N: это картинка, которая не прошла внутреннюю проверку даже после повтора. Мы её всё равно отдаём, а использовать ли её, решаете вы.

Список готовых пачек аккаунта (в том числе сделанных на сайте) — GET /marketplace-cards/generations (поля limit до 100 и before_id — номер последней уже виденной пачки). Идущая пачка в списке не показывается: спросите её по номеру. Незнакомый или чужой номер даёт 404 RESOURCE_NOT_FOUND.

Сколько стоит

Число слайдов выбирает план, поэтому цена не одна, а вилка. Ничего не списывая, её показывает расчёт:

curl -sS -X POST -H "Authorization: Bearer $ARK_KEY" \
  https://arckep.ru/api/v1/marketplace-cards/estimate

В ответе cost_min_rub (одно фото, меньше всего слайдов), cost_typical_rub (одно фото, 4 слайда), cost_max_rub (8 фото, 12 слайдов), границы по слайдам и фото и список площадок. Суммы уже с вашей скидкой; если она есть, прайс-лист лежит в list_cost_min_rub и list_cost_max_rub. На 22 октября 2026 вилка была 34,00 / 41,82 / 125,63 ₽: смотрите расчёт, а не эти числа.

Деньги не резервируются. Чтобы начать, на балансе (личном или организации) должно быть не меньше cost_max_rub, иначе 402 INSUFFICIENT_BALANCE и ничего не запускается. Пачка списывается один раз, по настоящей цене, когда план готов и известно число слайдов. Если пачка не получилась, списанное возвращается целиком. Повторы и проверки качества внутри пачки сверх цены не списываются. Пачки из API учитываются в GET /usage по ключу, который их запустил.

Для MCP-агентов

Те же операции доступны инструментами estimate_marketplace_cards, create_marketplace_cards, get_marketplace_cards и list_marketplace_cards. create_marketplace_cards отвечает сразу, а агент опрашивает get_marketplace_cards, пока статус не станет completed, и отдаёт пользователю картинки из output.images. Фото, которое пользователь дал агенту файлом, сначала загружают через upload_media и подставляют полученный url в image_urls.

Обычный запрос чата возвращает ответ сразу. Формат совместим с OpenAI, поэтому подходят готовые библиотеки — достаточно подменить адрес и ключ. Для большого объёма запросов доступна асинхронная пакетная обработка OpenAI и Anthropic.

В каталоге есть в том числе openai/gpt-6.1-sol, openai/gpt-6-sol, openai/gpt-6-luna, anthropic/claude-opus-5-5, anthropic/claude-sonnet-5-5, anthropic/claude-haiku-5-5, anthropic/claude-fable-5-1, meta/muse-wonder, inception/mercury-3, minimax/minimax-m3.1-flash, google-ai-studio/gemini-4-argon, qwen/qwen3.8-max-2026-09-02, z-ai/glm-5.3 и z-ai/glm-5.3-flash (рассуждения всегда включены), qwen/qwen3.8-flash и deepseek/deepseek-flash. Сообщения принимают текст и стандартные массивы частей content; модели с поддержкой зрения, включая DeepSeek Flash, Claude и Gemini, принимают изображения.

Модели OpenAI с окном 1,05 млн токенов (GPT-6.1 Sol, GPT-6 Sol, GPT-6 Luna, GPT-6 Astra, GPT-5.6, GPT-5.5 и GPT-5.4): если вход превышает 272 тысячи токенов (включая кеш), вход и кеш всего запроса тарифицируются с коэффициентом ×2, выход — ×1,5. Например, у GPT-6.1 Sol и GPT-6 Sol базовый тариф 220 ₽ за вход и 1100 ₽ за выход на миллион токенов, а свыше 272 тысяч — 440 ₽ и 1650 ₽ (чтение кеша у GPT-6.1 Sol — 11 ₽ или 22 ₽, у GPT-6 Sol — 22 ₽ или 44 ₽); у GPT-6 Luna — 11 ₽ / 55 ₽ до 272 тысяч и 22 ₽ / 82,5 ₽ свыше; у GPT-6 Astra — 1100 ₽ / 5500 ₽ и 2200 ₽ / 8250 ₽.

Claude Haiku 5.5: 11 ₽ за вход и 55 ₽ за выход на миллион токенов. Если запрос длиннее 100 тысяч токенов входа (кеш тоже считается), весь запрос стоит в 5 раз дороже — 55 ₽ и 275 ₽; чтение кеша — 1,1 ₽ или 5,5 ₽. В пакетной обработке цены вдвое ниже на обеих ступенях. Параметр temperature для этой модели игнорируется, а последнее сообщение ассистента (продолжение ответа) отбрасывается: запрос должен заканчиваться сообщением пользователя. По умолчанию Haiku 5.5 рассуждает адаптивно (усилие medium), а токены рассуждения входят в max_tokens: при совсем маленьком max_tokens передайте reasoning_effort со значением low, чтобы осталось место для ответа.

Meta Muse Wonder (meta/muse-wonder, превью): 464,20 ₽ за вход и 2321 ₽ за выход на миллион токенов, чтение кеша — 23,21 ₽; цена не зависит от длины запроса, контекст — 1 млн токенов. Рассуждения включены всегда: reasoning_effort принимает minimal, low, medium, high, xhigh и max, отключить их нельзя. Токены рассуждения входят в max_tokens и оплачиваются как выход, поэтому оставляйте запас: при маленьком лимите ответ придёт пустым (минимум — 16). Параметр tool_choice принимает только auto, остальные значения вернут 400.

Inception Mercury 3 (inception/mercury-3): диффузионная текстовая модель со сверхбыстрой генерацией; контекст — 1 млн токенов, ответ — до 131 072 токенов, вход и выход только текстовые (картинки не принимаются). Базовая цена — 23,21 ₽ за вход и 81,24 ₽ за выход на миллион токенов, чтение кеша — 2,32 ₽; пока у Inception действует стартовая скидка 50 %, тариф вдвое ниже: 11,61 ₽ за вход, 40,62 ₽ за выход и 1,16 ₽ за кеш. По умолчанию модель рассуждает (medium); reasoning_effort со значением none выключает рассуждения для мгновенного ответа, а minimal, low, medium, high, xhigh и max задают глубину разбора. Допустимый диапазон temperature — от 0.5 до 1.0 (значения вне диапазона приводятся к границам).

MiniMax M3.1 Flash (minimax/minimax-m3.1-flash): 17,41 ₽ за вход и 69,63 ₽ за выход на миллион токенов, чтение кеша — 1,74 ₽ (10 % от входа); контекст — 1 млн токенов, ответ — до 524 288 токенов, принимает текст, картинки и видео. Рассуждения включены всегда и оплачиваются как выход: reasoning_effort принимает low, medium (по умолчанию), high, xhigh и max, отключить их нельзя (none и minimal вернут 400). Параметр tool_choice принимает только auto.

Gemini 4 Argon (google-ai-studio/gemini-4-argon): 440 ₽ за вход и 2200 ₽ за выход на миллион токенов, чтение кеша — 22 ₽, контекст — 1 млн токенов, ответ — до 65 536 токенов. До конца 30 ноября (по Москве) действует стартовая цена: 220 ₽ за вход, 1100 ₽ за выход и 11 ₽ за чтение кеша, а со следующего дня — цены выше. Рассуждения включены всегда и оплачиваются как выход: reasoning_effort принимает low, medium (по умолчанию) и high, значения none и minimal вернут 400. У моделей Gemini 3.6 Flash, 3.5 Flash и 3.1 Flash-Lite допустим ещё и minimal; выключить рассуждения нельзя ни у одной Gemini.

DeepSeek (deepseek/deepseek-flash и deepseek/deepseek-v4-pro) по умолчанию рассуждает перед ответом. reasoning_effort со значением none выключает рассуждения — ответ быстрее и дешевле; minimal и low — короткие рассуждения; medium, high и xhigh — обычные (так DeepSeek работает и без параметра); max — самые глубокие. Токены рассуждения оплачиваются как выход.

Если Gemini вызывает ваши функции, у первого вызова в шаге есть поле extra_content.google.thought_signature (при потоке — в дельте tool_calls, без потока — в message.tool_calls[i]). Верните tool_calls ассистента в следующем запросе без изменений, вместе с extra_content. Если поля нет, мы подставим заглушку Google, и запрос пройдёт, но качество ответа после вызова функции может упасть.

Обычный запрос

curl -sS -X POST https://arckep.ru/api/v1/chat/completions \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "messages": [
      {"role": "system", "content": "Отвечай кратко."},
      {"role": "user", "content": "Сколько будет 2+2?"}
    ],
    "stream": false,
    "temperature": 0.2,
    "max_tokens": 256
  }'

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "openai/gpt-5.4-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "4" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 1,
    "total_tokens": 25,
    "cost_rub": "0.0123",
    "cache_read_tokens": 0,
    "prompt_tokens_details": { "cached_tokens": 0 }
  }
}

Поле usage.cost_rub — наше дополнение к формату OpenAI: сколько списано за этот запрос в рублях. Приходит после фактического списания.

Статистика кэша приходит у любой модели: usage.cache_read_tokens — сколько токенов запроса провайдер взял из своего кэша (они дешевле), а usage.prompt_tokens_details.cached_tokens — то же число в стандартном для OpenAI поле. Записи в кэш — cache_creation_5m_tokens и cache_creation_1h_tokens — бывают у Claude и у моделей OpenAI, которые их тарифицируют; у остальных там 0. У OpenAI GPT-5.6 и новее в первом поле записи на 30 минут, во втором — на 12 часов (см. «Кэш OpenAI на 12 часов» ниже). Цифры взяты из того же ответа провайдера, по которому считается списание. Если провайдер не прислал данных об использовании, эти поля равны null. В потоке они приходят в последнем чанке с usage.

Кэширование запросов Claude

Для моделей anthropic/... кэш включён по умолчанию на 5 минут: Anthropic автоматически кэширует подходящий префикс запроса, дополнительных полей не нужно. Срок (5 минут, 1 час) или отказ от кэша задаётся у ключа: Настройки → API → «Ваши ключи» → «Кэш запросов Claude». Свой cache_control в запросе главнее срока ключа, но не отменяет «Не кэшировать». Повторяйте тот же префикс и модель в течение срока кэша; число попаданий приходит в usage.prompt_tokens_details.cached_tokens. Первая запись в кэш стоит на 25 % дороже обычного входа, чтение из кэша — по сниженной цене модели. Короткие запросы могут не достичь порога Anthropic для кэширования.

{
  "model": "anthropic/claude-sonnet-4-6",
  "messages": [
    {"role": "system", "content": "Длинная неизменная инструкция..."},
    {"role": "user", "content": "Сделай краткое резюме."}
  ],
  "cache_control": {"type": "ephemeral", "ttl": "1h"}
}

Срок ttl: 5m по умолчанию или 1h. Первая запись стоит соответственно 1,25× или 2× обычного ввода; чтение из кэша дешевле. Предварительная проверка баланса учитывает запись, окончательное списание — фактические токены Anthropic. Эти счётчики кэша приходят в usage у всех моделей (см. выше). Для других моделей сам параметр cache_control вернёт ошибку 400.

Кэш OpenAI на 12 часов

Модели OpenAI GPT-5.6 и новее (openai/gpt-6.1-sol, openai/gpt-6-sol, openai/gpt-6-luna, openai/gpt-6-astra, openai/gpt-5.6-*) сами кэшируют неизменное начало запроса: запись живёт не меньше 30 минут, отдельное поле не нужно. Чтобы кэш жил не меньше 12 часов, добавьте в запрос prompt_cache_options.

{
  "model": "openai/gpt-6-sol",
  "messages": [
    {"role": "system", "content": "Длинная неизменная инструкция (от 1024 токенов)..."},
    {"role": "user", "content": "Сделай краткое резюме."}
  ],
  "prompt_cache_options": {"ttl": "12h"}
}

Срок ttl: 30m (по умолчанию, как без поля) или 12h. Другое значение или лишний ключ вернёт ошибку 422. Параметр задаётся в каждом запросе, настройки ключа для него нет. Остальные модели (Claude, DeepSeek, GPT-5.5, GPT-5.4, o3 и другие) ответят ошибкой 400 с полем prompt_cache_options до списания и до начала потока. В пакетной обработке параметра нет.

Запись в кэш на 12 часов стоит 2,5× от цены входа, на 30 минут — 1,25× (это полные коэффициенты, а не надбавки). Чтение из кэша стоит одинаково: 0,1× от цены входа, у GPT-6.1 Sol — 0,05×. Выше 272 тысяч токенов входа все коэффициенты, как обычно, удваиваются.

Когда это выгодно: начало запроса не короче 1024 токенов, а обращения с ним идут реже, чем раз в 30 минут. Тогда со сроком по умолчанию каждый запрос платит новую запись ×1,25, а с 12h запись ×2,5 платится один раз, дальше идёт чтение ×0,1: вариант на 12 часов выходит дешевле с третьего обращения. Если запросы идут чаще раза в 30 минут, дешевле срок по умолчанию. 12 часов — это минимальный срок жизни записи. Если то же начало уже закэшировано на 30 минут, запрос с 12h — это новая запись на 12 часов по цене ×2,5.

Предварительная проверка баланса считает весь запрос записью на 12 часов, окончательное списание идёт по фактическим токенам OpenAI. В usage записи на 30 минут приходят в cache_creation_5m_tokens (×1,25), записи на 12 часов — в cache_creation_1h_tokens (×2,5), чтение — в cache_read_tokens и prompt_tokens_details.cached_tokens.

Пакетная обработка OpenAI и Anthropic

Нативный Batch API выполняет задания асинхронно в окне до 24 часов. Цена токенов — половина обычной цены чата. Укажите модель OpenAI или Anthropic и от 1 до 100 текстовых заданий с уникальными custom_id. Инструменты и поиск в интернете здесь не поддерживаются; для Claude можно указать cache_control внутри задания. Одно задание OpenAI ограничено оценкой 240 000 байт входа с запасом на служебные токены, чтобы снизить риск попадания в более дорогой тариф за длинный контекст. Для GPT-5.6 и новее запись промпта в кэш OpenAI внутри Batch отключена.

curl -sS -X POST https://arckep.ru/api/v1/chat/batches \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Idempotency-Key: my-report-v1" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-6-luna","items":[
    {"custom_id":"row_1","messages":[{"role":"user","content":"Сделай краткое резюме."}],"max_tokens":512},
    {"custom_id":"row_2","messages":[{"role":"user","content":"Назови три риска."}],"max_tokens":512}
  ]}'

Ответ 202 содержит id, status и hold_rub — временный резерв в рублях. Проверяйте GET /chat/batches/{id} раз в 2–5 минут. После завершения заберите ответы через GET /chat/batches/{id}/results. Поле cost_rub — фактическая сумма; неизрасходованный резерв возвращается на баланс. Доступны также GET /chat/batches и POST /chat/batches/{id}/cancel. Результаты хранятся 30 дней. Ключ Idempotency-Key обязателен: повтор с тем же ключом не создаёт второе платное задание.

Потоковый ответ

С stream: true ответ отдаётся кусками в формате server-sent events, как у OpenAI. Поток заканчивается строкой data: [DONE], а в предпоследнем куске приходит usage с итоговой стоимостью.

curl -sSN -X POST https://arckep.ru/api/v1/chat/completions \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"xai/grok-4.3","messages":[{"role":"user","content":"Привет"}],"stream":true}'

Через библиотеку OpenAI

from openai import OpenAI

client = OpenAI(
    api_key="ark_live_…",           # ключ должен иметь право chat:write
    base_url="https://arckep.ru/api/v1",
)

r = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[{"role": "user", "content": "Привет"}],
)
print(r.choices[0].message.content)

Вызов функций

Модель может попросить вызвать вашу функцию. Опишите функции в поле tools в формате OpenAI. Выполняете их вы у себя — мы ничего не запускаем, только передаём запрос и ответ.

{
  "model": "openai/gpt-5.4-mini",
  "messages": [{"role": "user", "content": "Какая погода в Берлине?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Текущая погода по городу",
      "parameters": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      }
    }
  }],
  "tool_choice": "auto"
}

Если модель решила вызвать функцию, в ответе будет finish_reason: tool_calls и список вызовов. Выполните их и продолжите диалог, добавив сообщения с ролью tool и полем tool_call_id. Несколько вызовов за один ход поддерживаются.

Поиск в интернете

Флаг web_search: true заставляет модель искать свежие данные в интернете. У Claude, Gemini и Grok это встроенный поиск провайдера. У всех остальных моделей — DeepSeek, OpenAI, Qwen и моделей через OpenRouter — поиск делаем мы: добавляем к запросу два служебных инструмента (arckep_web_search и arckep_web_fetch), модель просит поиск, мы выполняем его и возвращаем результат, пока она не ответит. Вы получаете только готовый ответ; с stream: true текст приходит после поисков. Ваши собственные инструменты работают как обычно. За один запрос — не больше пяти кругов модели и пяти поисков. Какой способ у модели — видно в каталоге, в поле web_search_mode: provider или arckep.

curl -sS -X POST https://arckep.ru/api/v1/chat/completions \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google-ai-studio/gemini-3.8-flash",
    "messages": [{"role": "user", "content": "Что сегодня в новостях технологий?"}],
    "web_search": true,
    "max_tokens": 1024
  }'

Ограничения запроса

Картинку можно передать частью image_url внутри массива content(HTTPS URL или data URL). Для Gemini у HTTPS URL должно быть расширение изображения или явный MIME-тип. Диалоги через API не сохраняются в истории веб-студии: остаются только записи о списаниях.

Модели решений отвечают на готовые вопросы: да или нет, один вариант из вашего списка, место на вашей шкале. В ответе вероятность, а не сочинение. Этот адрес не пишет письма, подписи и объяснения — для текста по-прежнему чат. Моделей две: typesafe/jev-1.13 — только текст, дешевле; openai/gpt-6-luna-decisions — текст и картинки, длинный вход.

Jev: один запрос — несколько вопросов

В state кладёте текст или объект, про который спрашиваете. В questions — объект с вопросами. Формулировку и описание вариантов можно передать текстом или объектом, как в их API. Необязательные поля session_id, user и trace тоже проходят. Выбор другого поставщика не принимается: у этой модели он один. Вопросы считаются вместе и не видят ответов друг друга. Короткие имена jev-1.13 и jev-latest принимаются и считаются по цене этой же версии.

curl -sS -X POST https://arckep.ru/api/v1/decisions \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-1.13",
    "state": "После оплаты экран пустой. Пробовал два браузера.",
    "questions": {
      "is_bug": {
        "type": "noul",
        "instructions": "Клиент сообщает о поломке?",
        "criteria": {
          "true": "Описывает сломанное поведение",
          "false": "Задаёт вопрос или просит функцию"
        }
      },
      "team": {
        "type": "choice",
        "instructions": "Какая команда должна взять заявку?",
        "criteria": {
          "payments": "Оплата и счета",
          "frontend": "Вёрстка и браузер"
        }
      }
    }
  }'

{
  "id": "gen-dec-…",
  "object": "decision",
  "model": "typesafe/jev-1.13",
  "answers": {
    "is_bug": { "type": "noul", "noul": 0.96 },
    "team": {
      "type": "choice",
      "choice": "payments",
      "confidence": 0.75,
      "probabilities": { "payments": 0.83, "frontend": 0.17 }
    }
  },
  "usage": {
    "input_tokens": 476,
    "output_tokens": 70,
    "cost_rub": "0.0022"
  }
}

• На счёте должно быть хотя бы 5 ₽, как у чата. Сам запрос стоит доли копейки: вход около 4,62 ₽ за миллион токенов, выход бесплатно.
• Списание после успешного ответа. Если вопрос отклонён, деньги не списываются.
• Картинки, звук и файлы Jev не принимает — только текст. Окно около 32 тысяч токенов, до 32 вопросов, до 64 вариантов в списке, до 10 ступеней на шкале.

GPT-6 Luna: текст и картинки

Модель в каталоге: openai/gpt-6-luna-decisions. На этом адресе принимаются и короткие имена gpt-6-luna, gpt-6-luna-decisions, openai/gpt-6-luna — все считаются по одной цене. В input кладёте строку или список сообщений от user: внутри части input_text и input_image в любом порядке. Картинка — только base64 в data-URL (data:image/png;base64,…; ещё JPEG, WEBP и GIF без анимации). Ссылки на картинки и идентификаторы файлов не принимаются. У картинки есть detail: low, high, auto (по умолчанию) или original. В questions — список вопросов, у каждого обязательное уникальное name: по нему мы собираем ответы в объект.

curl -sS -X POST https://arckep.ru/api/v1/decisions \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-luna-decisions",
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "Обложка товара из карточки." },
          { "type": "input_image", "image_url": "data:image/png;base64,iVBORw0…", "detail": "auto" }
        ]
      }
    ],
    "questions": [
      { "type": "predicate", "name": "has_text", "instructions": "На картинке есть текст?" },
      {
        "type": "choice",
        "name": "category",
        "instructions": "Что изображено?",
        "choices": [
          { "value": "clothes", "description": "Одежда и обувь" },
          { "value": "electronics", "description": "Техника" },
          { "value": "other" }
        ]
      },
      {
        "type": "score",
        "name": "quality",
        "instructions": "Насколько снимок годится для витрины?",
        "levels": [
          { "label": "плохо", "description": "Размыто или тёмно" },
          { "label": "нормально" },
          { "label": "отлично", "description": "Резко, ровный свет" }
        ]
      }
    ]
  }'

{
  "id": "dec-…",
  "object": "decision",
  "model": "openai/gpt-6-luna-decisions",
  "provider": "OpenAI",
  "answers": {
    "has_text": { "type": "predicate", "probability": 1.0 },
    "category": {
      "type": "choice",
      "choice": "clothes",
      "probabilities": [
        { "value": "clothes", "probability": 0.91 },
        { "value": "electronics", "probability": 0.02 },
        { "value": "other", "probability": 0.07 }
      ],
      "confidence": 0.9
    },
    "quality": { "type": "refusal" }
  },
  "usage": {
    "input_tokens": 1306,
    "output_tokens": 0,
    "cost_rub": "0.0144"
  }
}

• Цена: обычный вход 11 ₽ за миллион токенов, чтение из кэша — 1,10 ₽ за миллион (0,1×), запись в кэш — 13,75 ₽ за миллион (1,25×), выход бесплатно. Картинка 1024×1024 — около 1230 токенов, то есть полторы копейки. Списание по токенам, которые насчитал поставщик, после успешного ответа. Ответ-отказ (refusal) тоже оплачивается по входным токенам.
• Окно 272 тысячи токенов: больше мы не отправим, запрос вернёт ошибку до вызова модели. При detail low, high или auto каждая картинка в этой оценке занимает не больше примерно 3 000 токенов (спишем по токенам поставщика). Если поставщик всё же насчитает больше, весь запрос считается по двойной ставке (22 / 2,20 / 27,50 ₽ за миллион).
• Пределы: от 1 до 400 вопросов, в choice от 2 до 255 вариантов, в score от 2 до 10 ступеней, до 128 картинок на запрос (включая картинки в input, ответах инструментов и instructions вопросов). Картинка крупнее 30 тысяч блоков 32×32 после уменьшения отклоняется — уменьшите её или не ставьте original.
• Структурированный вход и история: в сообщениях user и в instructions вопросов поддерживаются части input_text, input_image (только data URL в base64, чтобы размер в блоках 32×32 проверялся до вызова без внешних сетевых запросов) и input_json (объект или массив объектов до 256 КБ, глубина до 32, до 10 000 значений). В input также можно передать сообщения developer, system, assistant и парные вызовы инструментов (function_call / function_call_output, custom_tool_call / custom_tool_call_output).
• Кэширование префикса: поддерживаются prompt_cache_key (1–64 символа), prompt_cache_options (ttl: "30m", mode "implicit" или "explicit") и до 4 явных меток prompt_cache_breakpoint: {"mode": "explicit"} на частях input_text и input_image в input. Поля session_id, trace и выбор поставщика эта модель не принимает. user, safety_identifier и prompt_cache_key уходят поставщику только в виде необратимого хеша вместе с номером вашего аккаунта.
• Формат Jev тоже принимается: пришлите state и объект questions с noul / choice / score, сменив только model. Мы переведём его в формат OpenAI; минимумы OpenAI при этом действуют: два варианта в списке, две ступени на шкале.

Общее для обеих моделей

• Повтор с тем же заголовком Idempotency-Key в течение суток возвращает тот же ответ и не вызывает модель второй раз.
• Вместе с чатом действует общий предел одновременных запросов на ключ.

Как получить надёжные ответы

Цифры ниже — из нашего прогона на 1 193 коротких строках. Это ориентиры, а не гарантия: порог подбирайте на своей размеченной выборке.

• Один вопрос — одна тема. Вопрос, в котором смешано пять-восемь тем, дал 0,05 на заведомо чувствительный случай; те же темы по отдельности его поймали.
• Для порогов берите вопросы «да или нет» (predicate, noul). Для «есть ли риск» ставьте низкий порог, около 0,1; для «понятно ли клиенту» — около 0,5.
• Текст вопросов входит в каждый запрос и оплачивается: в среднем около 165 входных токенов на русский вопрос из двадцати пяти слов, то есть около 0,002 ₽ у Luna. Формулировки держите короткими.
• Одинаковый запрос возвращал те же числа (проверили на десяти строках, по два раза). Гарантии нет: фиксированного seed у моделей нет. Кэшируйте ответы по хешу вопросов и текста.
• Отсутствие ответа или refusal — не «нет». В нашем прогоне таких ответов не было, но обработайте их заранее и не пропускайте такой случай автоматически.
• Ваш текст и картинки уходят поставщику модели (Luna — OpenAI, Jev — TypeSafe). Пароли, ключи и персональные данные уберите до отправки обычными правилами.
• В usage.cost_rub — цена запроса по каталогу, с долями копейки. С баланса уходят целые копейки: сумма округляется вверх, а излишек остаётся на вашем счёте запасом и покрывает следующие запросы. Поэтому один дешёвый запрос может не изменить баланс, а другой — снять копейку. В сумме списанное равно сумме cost_rub с точностью до одной копейки.

Два адреса, которые дают интернет любой модели: локальной, из своего агента или из любого сервиса, где модель умеет вызывать функции. Модель просит поиск, ваш код отправляет вызов сюда, ответ возвращается ей в контекст. Работают без ожидания и без заданий, поиск выполняет DeepSeek. Флаг web_search у языковых моделей использует их же: у Claude, Gemini и Grok поиск встроен в модель, а у остальных мы сами крутим цикл с этими двумя инструментами. Адреса ниже нужны, когда вы хотите вести цикл сами, со своей моделью или своими запросами.

• Права ключа те же, что у чата: галочка «Чат-модели». Новый ключ не нужен, если чат у ключа уже включён.
• Платный только запрос, который вернул результат. Пустая выдача, ошибка, таймаут и страница, которую не удалось прочитать, бесплатны. Число результатов и режим need_content цену не меняют.
• Списание после ответа. Если на балансе меньше цены одного запроса, придёт 402 INSUFFICIENT_BALANCE.
• До 10 запросов одновременно на ключ, плюс обычные лимиты ключа в минуту и в сутки.
• Текст запроса и адрес страницы уходят в DeepSeek, сервера которого находятся в Китае. Не кладите в запросы персональные данные. У нас запрос и текст страницы не хранятся, в журнале списаний остаются только счётчики.

Поиск

curl -sS -X POST https://arckep.ru/api/v1/tools/search \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "цены deepseek api site:deepseek.com", "count": 3}'

{
  "id": "search-1f0c…",
  "object": "web_search",
  "query": "цены deepseek api site:deepseek.com",
  "results": [
    {
      "title": "Models & Pricing",
      "url": "https://api-docs.deepseek.com/quick_start/pricing",
      "snippet": "Краткое описание, около 200 символов",
      "summary": "Длинное описание для модели, бывает до 2–3 тысяч символов",
      "content": "",
      "site_name": "DeepSeek API Docs",
      "date": "2026-10-17T00:00:00Z",
      "rerank_score": 2.1,
      "authority": 3
    }
  ],
  "cost_rub": "0.1000",
  "currency": "RUB"
}

rerank_score — от 0 до 3, от 1,5 результат считается сильным. authority — авторитетность источника от 0 до 4, -1 если неизвестна, от 3 высокая. date, site_name и site_icon могут быть null. Поиск почти всегда что-то находит, даже на бессмысленный запрос: слабые совпадения видны по низкому rerank_score (на пробе — около 0,2), отсекайте их у себя. Платный запрос — любой, в котором результаты пришли.

Чтение страницы

curl -sS -X POST https://arckep.ru/api/v1/tools/fetch \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/docs/page"}'

В ответе title, content (текст страницы в Markdown), url и цена. Принимаются только адреса http:// и https:// без логина и пароля. Результат зависит от сайта и его правил доступа: закрытую страницу прочитать не получится, и это бесплатно.

Как подключить к своей модели

Опишите две функции в формате вашей модели (ниже формат OpenAI) и, когда модель вызывает функцию, отправьте её аргументы как есть на соответствующий адрес. Ответ положите в сообщение с результатом инструмента.

[
  {"type": "function", "function": {
    "name": "web_search",
    "description": "Search the web. Returns ranked results with title, url, snippet and summary. Use site:, \"exact phrase\", after:YYYY-MM-DD in the query.",
    "parameters": {"type": "object", "required": ["query"], "properties": {
      "query": {"type": "string", "maxLength": 128},
      "count": {"type": "integer", "minimum": 1, "maximum": 50, "default": 5}}}}},
  {"type": "function", "function": {
    "name": "web_fetch",
    "description": "Read one web page (http or https) and return its text as Markdown.",
    "parameters": {"type": "object", "required": ["url"], "properties": {
      "url": {"type": "string"}}}}}
]

DeepSeek Harness

У программы DeepSeek Harness свой «Поиск в интернете»: она ходит за ним на адрес в формате Anthropic Messages и без собственного ключа DeepSeek пишет «DeepSeek search has no API key». Адрес POST /api/v1/messages принимает именно такой запрос и отвечает тем же поиском, что и /tools/search: те же права ключа, та же цена 0,10 ₽ за успешный запрос, пустая выдача бесплатна. Ничего, кроме поиска, он не делает: чат идёт через /chat/completions.

• В программе: Plugins → Built-in plugin settings → Web search → поле Messages API base URL = https://arckep.ru/api/v1 (в старых сборках: Settings → Plugins → Plugin configuration → Web search → Endpoint). Окончание /messages программа добавит сама.
• Ключ: поиск берёт его из записи DEEPSEEK_API_KEY. Сохраните туда на странице Models свой ключ arckep (ark_live_…). Если стоит плагин dsh-arckep и ключ уже лежит в ARCKEP_API_KEY, укажите apiKeyEnv: ARCKEP_API_KEY для @deepseek-ai/dsh-web-search-deepseek в cordis.patch.yml.
• Переключатель «Use the new Web Search API» тоже работает: тогда программа ходит на …/api/v1/search и …/api/v1/fetch, а это то же самое, что /tools/search и /tools/fetch. Поэтому адрес остаётся один на оба режима, https://arckep.ru/api/v1, и цена та же.
• Запрос длиннее 128 знаков укорачивается по слову, а не отклоняется. Подробности и пример ответа: руководство /docs/api.md, раздел 4.6.1.

Ошибки

Любая из этих ошибок бесплатна.

Цены такие же, как в студии. Списывается с вашего личного баланса, а если вы состоите в активной организации — с её счёта; в ответе это видно в поле charged_from.

Картинки: сначала резерв, потом сверка

При постановке задачи с баланса резервируется расчётная стоимость. Когда картинка готова, сумма сверяется с фактической: разница либо доплачивается, либо возвращается. Если генерация не удалась или сработал фильтр безопасности — резерв возвращается целиком.

Резерв берётся до обращения к провайдеру. Поэтому несколько параллельных задач не могут суммарно потратить больше, чем есть на балансе.

Карточки для маркетплейсов: списание по готовности плана

Пока план не готов, ничего не списывается: для старта на балансе должна быть сумма самой большой пачки (cost_max_rub из расчёта). Когда план составлен и известно число слайдов, пачка списывается один раз по своей цене. Если она не получилась, деньги возвращаются целиком.

Видео: оплата вперёд

Здесь сумма списывается сразу при постановке задачи. Если провайдер не принял задачу или ролик в итоге не получился, деньги возвращаются автоматически — отдельно просить возврат не нужно.

3D: расчёт перед запуском

Hunyuan при запуске держит максимум для выбранных настроек (57,50–77,63 ₽) и возвращает разницу, если итог получился меньше. Meshy, Tripo и Rodin списывают точную цену выбранных настроек: 92–174,80 ₽, 11,50–69 ₽ и 11,50–138 ₽ (Rodin: быстрый вариант 11,50 ₽, обычный 46 ₽, обычный с текстурами 4K 138 ₽). При ошибке возвращаем списанную сумму.

Распознавание речи: оплата по результату

Перед вызовом поставщика проверяется, что баланса хватает на оценку (с запасом), и эта сумма придерживается, пока идёт распознавание. Списание — после того как текст получен, по токенам, которые вернул Google. Сумма округляется вверх до копейки. Если поставщик не ответил, ничего не списывается.

Чат: оплата по факту

Заранее списать нельзя — стоимость зависит от длины ответа, которую заранее никто не знает. Поэтому перед запросом проверяется, что баланса хватает на предполагаемую стоимость, а списание происходит после ответа, по фактическому расходу токенов.

У OpenAI GPT-5.6 и новее запись входных токенов в кэш стоит 1,25× цены ввода, чтение из кэша — 0,1×, обычный ввод — 1×. Предварительная проверка учитывает возможную запись всего запроса в кэш; фактическая сумма зависит от ответа провайдера.

Узнать цену заранее

Для картинок, видео, 3D, карточек для маркетплейсов и распознавания речи есть расчёт без запуска: POST /images/estimate, POST /videos/estimate, POST /models3d/estimate, POST /marketplace-cards/estimate и POST /audio/transcriptions/estimate. Считают тем же кодом, что и настоящее списание, поэтому расхождений быть не должно.

Для чата и для решений (Jev, GPT-6 Luna) предварительной оценки нет — ориентируйтесь на цены за миллион токенов из каталога (поле pricing_rub_per_1m). У моделей решений платный только вход, выход бесплатный. На счёте перед запросом должно быть хотя бы 5 ₽.

Ограничения частоты

При превышении приходит HTTP 429 с кодом RATE_LIMIT_EXCEEDED. В details указано, какой именно предел сработал — по этому полю удобно решать, ждать секунду или минуту. Лимиты считаются на ключ, поэтому не раздавайте один ключ десяти воркерам.

Защита от двойного списания

При создании картинки, видео и при распознавании речи передавайте заголовок Idempotency-Key с уникальным значением, например UUID. Если запрос оборвётся по таймауту и вы повторите его с тем же ключом, заново ничего не запустится — вы получите тот же ответ: тот же номер задачи или тот же текст распознавания.

Idempotency-Key: 6f1c0a4e-6c1a-4c94-a0f2-6f0b6f0f5f1a

Для чата заголовок не нужен: ответ приходит сразу, повторять нечего.

Есть два способа: спрашивать статус самому или получить уведомление на свой адрес. Для промышленных сценариев лучше уведомления — они не тратят лимит запросов и приходят сразу.

Ставьте у себя разумный таймаут: картинки обычно готовы меньше чем за две минуты, видео — от минуты до часа в зависимости от модели и длительности. Если провайдер завис, наша фоновая проверка сама закроет задачу и вернёт деньги.

Мы отправляем POST-запрос на ваш адрес, когда задача завершилась — успешно или нет. Адрес задаётся один раз для ключа или отдельно для каждой задачи полем webhook_url.

Какие события приходят

{
  "id": 123,
  "object": "image.generation",
  "status": "completed",
  "model": "gemini-3.1-flash-image",
  "cost_rub": "4.24",
  "error": null,
  "output": {
    "images": [{ "url": "https://arckep.ru/…" }]
  }
}

Проверка подлинности

Вместе с телом мы присылаем подпись. Она доказывает, что запрос отправили мы, а не кто-то, кто узнал ваш адрес. Секрет для проверки выдаётся один раз при создании ключа — там же, где сам ключ.

import hmac, hashlib

def verify(secret: str, raw_body: bytes, signature_hex: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_hex or "")

Секрет можно сменить, не трогая сам ключ: POST /api/developer/keys/{id}/rotate-webhook-secret. Новый секрет тоже показывается один раз, старый сразу перестаёт работать.

Повторы и надёжность

• Отвечайте кодом 2xx как можно быстрее, тяжёлую работу делайте потом у себя.
• Если ваш сервер не ответил или вернул ошибку, доставка повторяется с нарастающими паузами, до 5 попыток.
• Очередь доставок хранится в базе, поэтому перезапуск нашего сервиса ничего не теряет.
• Один и тот же номер доставки может прийти несколько раз — учитывайте это и не выполняйте действие дважды.

Требования к адресу

Адрес должен быть на HTTPS и вести на публичный хост. Локальные и внутренние адреса отклоняются при сохранении — это защита от использования нашего сервера как посредника для доступа к чужим внутренним сетям.

• Только HTTPS.
• Нельзя localhost, внутренние диапазоны IP, служебные адреса и домены вроде .local или .internal.
• Проверка идёт после разрешения имени, так что подменить домен на внутренний IP не выйдет.

Если нужно принимать вебхуки на машине без публичного адреса, используйте туннель (ngrok, Cloudflare Tunnel) — он даёт настоящий HTTPS-адрес.

Все ошибки приходят в одном формате. Ориентируйтесь в коде на поле error_code, а не на текст сообщения: формулировки мы улучшаем, коды не меняем.

{
  "error_code": "INSUFFICIENT_BALANCE",
  "message": "Insufficient personal balance: need 15.00 ₽, available 5.00 ₽…",
  "details": {
    "required": 15.0,
    "available": 5.0,
    "is_corporate": false,
    "currency": "RUB"
  }
}

Сообщения приходят на английском — так их проще показывать в логах и передавать в поддержку. Ниже перевод и что делать в каждом случае.

Как обрабатывать правильно

Картинка от начала до конца

Скрипт загружает исходник, ставит задачу с защитой от двойного списания и ждёт результат.

export ARK_KEY="ark_live_..."
export BASE="https://arckep.ru/api/v1"

# 1. Загрузить исходник (если нужен)
UP=$(curl -sS -X POST "$BASE/uploads" \
  -H "Authorization: Bearer $ARK_KEY" \
  -F "file=@./input.png")
REF_URL=$(echo "$UP" | jq -r .url)

# 2. Поставить задачу
JOB=$(curl -sS -X POST "$BASE/images/generations" \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{
    \"model\": \"gemini-3.1-flash-image\",
    \"prompt\": \"кот-космонавт, студийный свет\",
    \"reference_image_urls\": [\"$REF_URL\"]
  }")
ID=$(echo "$JOB" | jq -r .id)

# 3. Ждать результат
while true; do
  S=$(curl -sS -H "Authorization: Bearer $ARK_KEY" "$BASE/images/generations/$ID")
  ST=$(echo "$S" | jq -r .status)
  echo "$S" | jq -c '{status, cost_rub, error}'
  [ "$ST" = "completed" ] && echo "$S" | jq -r '.output.images[].url' && break
  [ "$ST" = "failed" ] && echo "Ошибка: $(echo "$S" | jq -r .error)" && break
  sleep 3
done

3D по фото

UP=$(curl -sS -X POST "$BASE/uploads" \
  -H "Authorization: Bearer $ARK_KEY" \
  -F "file=@./object.png")
REF=$(echo "$UP" | jq -r .url)

curl -sS -X POST "$BASE/models3d/generations" \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{
    \"model\": \"hunyuan-3d-3.1\",
    \"image_url\": \"$REF\"
  }"

Видео по тексту

curl -sS -X POST "$BASE/videos/generations" \
  -H "Authorization: Bearer $ARK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "veo-3.1-fast-generate-preview",
    "prompt": "волны на пляже, золотой час",
    "mode": "t2v",
    "duration_seconds": 6
  }'

Приём вебхука на Python

import hmac, hashlib
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
SECRET = "…секрет вебхука, показан один раз при создании ключа…"

@app.post("/hooks/arckep")
async def arckep_hook(request: Request):
    raw = await request.body()            # именно сырые байты
    signature = request.headers.get("X-Arckep-Signature", "")
    expected = hmac.new(SECRET.encode(), raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, signature):
        raise HTTPException(status_code=401, detail="bad signature")

    event = request.headers.get("X-Arckep-Event")
    payload = await request.json()
    # Отвечаем быстро, обработку ставим в очередь
    enqueue(event, payload)
    return {"ok": True}

Подключение в n8n

• Узел HTTP Request, метод POST, адрес https://arckep.ru/api/v1/images/generations.
• Авторизация: заголовок Authorization со значением Bearer ark_live_…. Храните ключ в Credentials, а не в теле узла.
• Дальше либо узел ожидания и повторный запрос статуса, либо узел Webhook как приёмник уведомления — второй вариант надёжнее и не тратит лимит.

Языковая модель через библиотеку OpenAI

from openai import OpenAI

client = OpenAI(api_key="ark_live_…", base_url="https://arckep.ru/api/v1")

stream = client.chat.completions.create(
    model="anthropic/claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Объясни рекурсию за три предложения"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)