Утилиты и монтаж

Девять модулей: C2PA Signer Profiles, FORSAJ, HOLST, INDEXLIFT, KLEY, OVERLAY, PLASTINKA, SPEKTR и SUFLER. Контракты сверены с исходниками 8 сентября 2026 года; доступ зависит от аккаунта и выбранной операции.

Подключение и загрузка

Сохраните API-ключ в переменной окружения FRANKLAB_KEY. База примеров — https://apergrex.ru; пути ниже уже включают полный /franklab/api. Повтор franklab в /franklab/api/franklab/jobs обязателен. Для SPEKTR/Recraft используется X-API-Key, для остальных примеров — Authorization: Bearer. Не передавайте partnerId.

export FRANKLAB_ORIGIN="https://apergrex.ru"
# FRANKLAB_KEY is supplied by your secret manager
curl --fail-with-body "$FRANKLAB_ORIGIN/franklab/api/franklab/jobs/upload" \
  -H "Authorization: Bearer $FRANKLAB_KEY" \
  -F "file=@synthetic.mp4;type=video/mp4"

Возьмите data.url ответа загрузки и замените им https://example.com/synthetic.* в примерах; это адреса-заполнители, не готовые медиа. Максимум 150 MiB, срок хранения источника 7 дней. MIME: video/mp4, video/webm, video/quicktime, video/x-msvideo; audio/mpeg, audio/mp3, audio/wav, audio/ogg, audio/pcm, audio/l16, audio/x-pcm; image/png, image/jpeg, image/gif, image/webp. Загрузка не преобразует формат. URL должны быть доступны серверу; локальные/частные адреса и запрещённые перенаправления не подходят. Сохраняйте готовый результат до expiresAt, если поле присутствует.

Проверка подключения: GET /franklab/api/franklab/integrations/text-sticker/auth/stats с ключом. Для SPEKTR Make читает GET /franklab/api/v1/images/omni-image?pageNum=1&pageSize=1. Это чтение истории и проверка ключа, не тест генерации.

Статус, результат и списание

Успешная отправка возвращает HTTP 200 и success:true, но это ещё не готовый файл. Для задач jobs храните data.taskId, опрашивайте свой маршрут каждые 5 секунд до data.status=completed или failed. queued и processing — промежуточные состояния. Ограничьте время ожидания; при таймауте продолжайте читать существующий ID. Не повторяйте POST автоматически после сетевой ошибки.

Для задач jobs final_cost_franks сопровождается cost_currency=FRANK, cost_status и cost_unit. Пока cost_status=reserved, сумма — резерв; final означает итог, refunded — возврат, unavailable — отсутствие достоверной цены. Франк — внутренняя учётная единица, не валюта. Не считайте отсутствие поля нулевой ценой. Тариф и разрешённые функции проверяются сервером. Для обычных утилит отдельный REST-маршрут оценки стоимости не подтверждён; оценка стоимости Studio не является универсальной оценкой утилит. Операция list C2PA бесплатна в исходном контракте; остальные операции профилей могут тарифицироваться. Прямая передача запросов Recraft и синхронный INDEXLIFT не доказывают этот договор списания.

Ошибки HTTP 400 обычно означают параметры/несовместимую комбинацию, 401 — ключ, 404 — ресурс, 429 — ограничение частоты; 5xx и ошибки провайдера требуют проверки существующей задачи. success:true с data.status=failed остаётся неуспехом. Диагностические операции могут возвращать metadataReport/metrics/qcReport без файла; их доступность отмечена отдельно.

Content Credentials (C2PA)

Поддерживающие jobs принимают c2paSigningMode=off|franklab|user_profile, c2paSignerProfileId для user_profile, contentOrigin=not_declared|human_edited|ai_assisted|ai_generated|human_created|camera_captured. Дополнительные строки: humanAuthorName, humanAuthorUrl, reviewedBy, reviewedAt, reviewMethod, c2paActionDescription, c2paDisclosure. Массивы sourceMaterialUrls и originalEvidenceUrls — до 10 публичных HTTPS URL каждый. Ограниченные заявления human_created/camera_captured требуют активного разрешающего профиля и доказательств. verifiedIncomingC2paIngredient в запросе не служит доказательством: результат проверяет сервер. Успешная подпись не равна доверенной цепочке: читайте отдельно c2paStatus, c2paSigned, c2paCryptographicallyValid, c2paTrustedChainValid, c2paCawgIdentityPresent, c2paPublicVerifierRecognized, c2paManifestUrl и c2paVerificationReport. OVERLAY make/jobs DTO не объявляет C2PA-поля.

C2PA Signer Profiles

Список возвращает только активные профили партнёра без PEM. Создание и ротация требуют собственного сертификата и ключа; generate_self_signed создаёт самоподписанный профиль. trustLevel=trusted через этот маршрут запрещён. Ротация создаёт новую версию; старый ID нельзя подменять новым. Отзыв меняет действительность профиля. Эти действия здесь не выполнялись.

Операции и минимальные JSON-запросы

Каждый пример ниже задаёт полный JSON для указанного POST; замените URL/ID собственными значениями. Опции поля operation или режима выбирают разные функции, а не разные модели генерации. Статус «источник» означает проверку кода без проверки работающего API и полного цикла выполнения; «блокировано» — известное ограничение.

curl --fail-with-body "$FRANKLAB_ORIGIN/franklab/api/make/c2pa/signer-profiles" \
  -H "Authorization: Bearer $FRANKLAB_KEY"

Поля REST

Поля относятся к выбранной операции; обязательность уточняется условием и минимальным примером. [] — элемент массива.

Опции Make и преобразование в REST

Это справочник выбора в Make; имена интерфейса не всегда совпадают с REST. Поля v1*/v2*, text* и sample* переводятся как описано выше. Вложенные условия относятся к интерфейсу Make.

Ответ и границы проверки

HTTP 200 {success:true,data:PROFILE[]}; profileId,id,label,status,trustLevel,allowRestrictedOriginClaims,version,profileGroupId,createdAt,updatedAt,rotatedAt,revokedAt; PEM-данные не возвращаются.

При ротации REST принимает необязательный allowRestrictedOriginClaims; отсутствие сохраняет старое значение. Текущая конфигурация communication Make не передаёт этот переключатель для rotate_from_pem.

FORSAJ

video_speed отправляет videoUrl и speed в jobs/video-speed. audio_speed отправляет аудиоссылку под именем videoUrl, operation=speed в jobs/audio. speed: 0.25–4. audioBitrate: строка 8k–320k; значение custom из Make заменяется реальным битрейтом. Поле mode не передаётся в REST. Для видео duration может отражать исходную длительность; проверяйте выходной файл.

Операции и минимальные JSON-запросы

Каждый пример ниже задаёт полный JSON для указанного POST; замените URL/ID собственными значениями. Опции поля operation или режима выбирают разные функции, а не разные модели генерации. Статус «источник» означает проверку кода без проверки работающего API и полного цикла выполнения; «блокировано» — известное ограничение.

curl --fail-with-body "$FRANKLAB_ORIGIN/franklab/api/franklab/jobs/video-speed" \
  -H "Authorization: Bearer $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"videoUrl":"https://example.com/synthetic.mp4","speed":1.1}'

Поля REST

Поля относятся к выбранной операции; обязательность уточняется условием и минимальным примером. [] — элемент массива.

Опции Make и преобразование в REST

Это справочник выбора в Make; имена интерфейса не всегда совпадают с REST. Поля v1*/v2*, text* и sample* переводятся как описано выше. Вложенные условия относятся к интерфейсу Make.

Ответ и границы проверки

HTTP 200 {success:true,data:{taskId,status,final_cost_franks,cost_currency,cost_status,cost_unit}}; опрашивайте статус по полученному taskId.

HOLST

Укажите imageUrl и либо operation, либо steps (до 20 шагов, каждый с op). outputFormat: jpeg/jpg/png/webp/avif/gif; outputQuality: 1–100. В текущем DTO верхнего уровня нет ряда полей Make: watermarkPosition/Opacity/Scale, textPosition/fontSize/color/font, brightness/saturation/hue/contrast/gamma, imageUrls/columns/gap/background. Для watermark, text, adjust и collage используйте steps с position/opacity/scale, content/fontSize/color, brightness и imageUrls/columns/gap соответственно. Поле font отсутствует даже в ImageStepDto: выбор шрифта для HOLST не подтверждён. removeBgProvider, alphaMatting, ocrLanguages, metadataEngine и includeGps доступны REST, но Make communication не отправляет их на верхнем уровне. OCR/remove_bg/strip_gps/read_metadata зависят от возможностей worker; info/read_metadata могут блокироваться проверкой обязательного выходного файла.

Операции и минимальные JSON-запросы

Каждый пример ниже задаёт полный JSON для указанного POST; замените URL/ID собственными значениями. Опции поля operation или режима выбирают разные функции, а не разные модели генерации. Статус «источник» означает проверку кода без проверки работающего API и полного цикла выполнения; «блокировано» — известное ограничение.

curl --fail-with-body "$FRANKLAB_ORIGIN/franklab/api/franklab/jobs/image" \
  -H "Authorization: Bearer $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"imageUrl":"https://example.com/synthetic.png","operation":"resize","width":64,"height":64}'

Поля REST

Поля относятся к выбранной операции; обязательность уточняется условием и минимальным примером. [] — элемент массива.

Опции Make и преобразование в REST

Это справочник выбора в Make; имена интерфейса не всегда совпадают с REST. Поля v1*/v2*, text* и sample* переводятся как описано выше. Вложенные условия относятся к интерфейсу Make.

Ответ и границы проверки

HTTP 200 {success:true,data:{taskId,status,final_cost_franks,cost_currency,cost_status,cost_unit}}; опрашивайте статус по полученному taskId.

Шаги sharpen принимают sigma; flat/jagged из Make не входят в REST DTO. Шаги write_exif не объявляют imageDescription/copyright/artist: используйте одиночную operation=write_exif.

Известное ограничение REST: info, read_metadata, ocr. Worker возвращает данные без основного файла, а контур задач требует его для завершения. Эти функции блокированы до отдельного исправления; не используйте их для пробного списания.

INDEXLIFT

execution_mode=sync вызывает audit-landing с {url,mode}; async_wait вызывает audit-landing/async и отдельный маршрут status. pageUrl из Make превращается в url. mode: single-page или crawl. Для повторного чтения используйте сохранённый taskId, не создавайте новую задачу. idempotency_key отсутствует в DTO: передавайте Idempotency-Key заголовком только для асинхронного режима. Синхронный маршрут передаёт ответ SEO-службы; он не доказывает единый биллинг или схему задач обработки медиа.

Операции и минимальные JSON-запросы

Каждый пример ниже задаёт полный JSON для указанного POST; замените URL/ID собственными значениями. Опции поля operation или режима выбирают разные функции, а не разные модели генерации. Статус «источник» означает проверку кода без проверки работающего API и полного цикла выполнения; «блокировано» — известное ограничение.

curl --fail-with-body "$FRANKLAB_ORIGIN/franklab/api/franklab/jobs/audit-landing/async" \
  -H "Authorization: Bearer $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://example.com/","mode":"single-page"}'

Для асинхронного POST добавьте -H "Idempotency-Key: your-unique-request-id". Одинаковый ключ используйте только для того же запроса.

Поля REST

Поля относятся к выбранной операции; обязательность уточняется условием и минимальным примером. [] — элемент массива.

Опции Make и преобразование в REST

Это справочник выбора в Make; имена интерфейса не всегда совпадают с REST. Поля v1*/v2*, text* и sample* переводятся как описано выше. Вложенные условия относятся к интерфейсу Make.

Ответ и границы проверки

Синхронный режим передаёт ответ SEO-сервиса; асинхронный режим: {success:true,data:{taskId,task_id,status:"queued",phase,idempotency_key,idempotency_hit,final_cost_franks,cost_currency,cost_status:"reserved",cost_unit}}.

Асинхронный INDEXLIFT использует zeroCost в исходниках и не открывает резерв. Это отдельная бесплатная схема выполнения, не платная задача обработки медиа; фактическое выполнение всё равно требует проверки. Проверка родительской задачи 8 сентября 2026 года обнаружила отчёт по пути data.result.data.seo_report: data.result сохраняет оболочку SEO-сервиса. Рекомендации, если присутствуют, читайте в data.result.data.brief_suggestions. Make сейчас читает верхний body.data.seo_report и может пропустить результат. При успешном асинхронном выполнении cost_status=confirmed с нулевой стоимостью, а не final обычного JobsFacade.

KLEY

Выбор operation определяет маршрут: speed → video-speed; subtitles → subtitles; overlay/image_on_video → overlay; остальные → montage. concat принимает videos[] с url и параметрами перехода к следующему клипу; поля перехода последнего элемента игнорируются. transitionSoundMode=none/auto/manual; manual требует transitionSoundPreset, громкость 0–1.5. Не передавайте отдельную строку transitionType на верхнем уровне. slideshow требует минимум 2 изображения; slideTransitionDuration меньше slideDuration. quality_compare требует referenceVideoUrl. Сравнения и анализ не гарантируют downloadUrl и требуют отдельной проверки выполнения.

Операции и минимальные JSON-запросы

Каждый пример ниже задаёт полный JSON для указанного POST; замените URL/ID собственными значениями. Опции поля operation или режима выбирают разные функции, а не разные модели генерации. Статус «источник» означает проверку кода без проверки работающего API и полного цикла выполнения; «блокировано» — известное ограничение.

curl --fail-with-body "$FRANKLAB_ORIGIN/franklab/api/franklab/jobs/montage" \
  -H "Authorization: Bearer $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"operation":"concat","videos":[{"url":"https://example.com/synthetic.mp4"},{"url":"https://example.com/synthetic.mp4"}]}'

Поля REST

Поля относятся к выбранной операции; обязательность уточняется условием и минимальным примером. [] — элемент массива.

Опции Make и преобразование в REST

Это справочник выбора в Make; имена интерфейса не всегда совпадают с REST. Поля v1*/v2*, text* и sample* переводятся как описано выше. Вложенные условия относятся к интерфейсу Make.

Ответ и границы проверки

HTTP 200 {success:true,data:{taskId,status,final_cost_franks,cost_currency,cost_status,cost_unit}}; опрашивайте статус по полученному taskId.

Известное ограничение REST: probe, quality_compare, qc_report, scenes. Worker возвращает данные без основного файла, а контур задач требует его для завершения. Эти функции блокированы до отдельного исправления; не используйте их для пробного списания.

OVERLAY

Создание и опрос идут через make/jobs. Ссылка результата находится в data.result.downloadUrl. overlays — массив до 20 объектов: type=text/sticker/animated_sticker/emoji/watermark, параметры зависят от type. Используйте ID справочников. Для текстового слоя content — текст, для watermark — imageUrl; не передавайте оба представления как один тип. platform и configId задают размещение.

Операции и минимальные JSON-запросы

Каждый пример ниже задаёт полный JSON для указанного POST; замените URL/ID собственными значениями. Опции поля operation или режима выбирают разные функции, а не разные модели генерации. Статус «источник» означает проверку кода без проверки работающего API и полного цикла выполнения; «блокировано» — известное ограничение.

curl --fail-with-body "$FRANKLAB_ORIGIN/franklab/api/make/jobs/overlay" \
  -H "Authorization: Bearer $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"videoUrl":"https://example.com/synthetic.mp4","overlays":[{"type":"text","content":"Synthetic test","x":50,"y":50,"fontSize":24,"color":"#FFFFFF"}]}'

Поля REST

Поля относятся к выбранной операции; обязательность уточняется условием и минимальным примером. [] — элемент массива.

Опции Make и преобразование в REST

Это справочник выбора в Make; имена интерфейса не всегда совпадают с REST. Поля v1*/v2*, text* и sample* переводятся как описано выше. Вложенные условия относятся к интерфейсу Make.

Ответ и границы проверки

HTTP 200 {success:true,data:{taskId,status,final_cost_franks,cost_currency,cost_status,cost_unit}}; опрашивайте статус по полученному taskId.

PLASTINKA

Проверка 8 сентября 2026 года: в примере trim с исходным WAV получен контейнер MP4 с копированием аудиопотока без перекодирования. Локальный декодер не распознал кодек результата, поэтому пригодность этого файла к воспроизведению не подтверждена. Наблюдение относится к этому сочетанию операции и входного формата.

Для аудиообработки исходная аудиоссылка называется videoUrl. Для overlay/replace/fit добавьте audioUrl либо sampleId; apply_sample из Make превращается в operation=sampleOperation (overlay/replace). merge принимает audioUrls[] и videoUrl, равный первому URL. save_sample возвращает ресурс с id, а не задачу: JSON {name,sampleUrl} либо multipart name+sampleFile, ровно один источник, до 50 MiB, mp3/wav/aac/m4a/ogg/flac. sampleEndTime должен быть больше sampleStartTime. sampleSourceMode=file показан в Make, но communication отправляет JSON без sampleFile; используйте прямой multipart REST.

Операции и минимальные JSON-запросы

Каждый пример ниже задаёт полный JSON для указанного POST; замените URL/ID собственными значениями. Опции поля operation или режима выбирают разные функции, а не разные модели генерации. Статус «источник» означает проверку кода без проверки работающего API и полного цикла выполнения; «блокировано» — известное ограничение.

curl --fail-with-body "$FRANKLAB_ORIGIN/franklab/api/franklab/jobs/audio" \
  -H "Authorization: Bearer $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"videoUrl":"https://example.com/synthetic.mp4","operation":"overlay","sampleId":"<SAMPLE_UUID>"}'

curl --fail-with-body "$FRANKLAB_ORIGIN/franklab/api/franklab/audio-samples" \
  -H "Authorization: Bearer $FRANKLAB_KEY" \
  -F "name=Synthetic sample" -F "sampleFile=@synthetic.wav;type=audio/wav"

Поля REST

Поля относятся к выбранной операции; обязательность уточняется условием и минимальным примером. [] — элемент массива.

Опции Make и преобразование в REST

Это справочник выбора в Make; имена интерфейса не всегда совпадают с REST. Поля v1*/v2*, text* и sample* переводятся как описано выше. Вложенные условия относятся к интерфейсу Make.

Ответ и границы проверки

HTTP 200 {success:true,data:{id,name,sourceUrl,mimeType,format,durationMs,clipStartTime,clipEndTime,isSystem,createdAt}}; опрос статуса задачи не требуется.

Известное ограничение REST: probe, quality_compare, analyze, fingerprint. Worker возвращает данные без основного файла, а контур задач требует его для завершения. Эти функции блокированы до отдельного исправления; не используйте их для пробного списания.

SPEKTR

Проверка 8 сентября 2026 года: тестовая задача waveform завершилась со статусом failed и возвратом средств (cost_status=refunded). Успешный результат этой операции не подтверждён; наблюдение не определяет состояние остальных операций SPEKTR.

background_remove использует X-API-Key и Recraft {model:"recraft/remove-background",input:{image:URL}}. Ответ провайдера: code/data.taskId; status — data.state, результат — JSON.parse(data.resultJson).resultUrls[]. Это прямая передача запроса без подтверждённого клиентского списания FrankLab. Остальные операции используют Bearer и jobs. waveform: audioUrl из Make → videoUrl; video_round → operation=round; video_remove_bg → operation=remove_bg. Bria replace image требует ровно одно из prompt/refImages; erase_by_text — objectName; lifestyle — sceneDescription. Для Bria video erase >5 секунд нужен autoTrim=true, фактическую длительность проверяет сервер. При возобновлении jobs через Make task_id возможен ошибочный выбор маршрута опроса Recraft; в REST сохраняйте маршрут вместе с ID.

Операции и минимальные JSON-запросы

Каждый пример ниже задаёт полный JSON для указанного POST; замените URL/ID собственными значениями. Опции поля operation или режима выбирают разные функции, а не разные модели генерации. Статус «источник» означает проверку кода без проверки работающего API и полного цикла выполнения; «блокировано» — известное ограничение.

curl --fail-with-body "$FRANKLAB_ORIGIN/franklab/api/franklab/jobs/montage" \
  -H "Authorization: Bearer $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"operation":"waveform","videoUrl":"https://example.com/synthetic.wav","width":320,"height":240}'

Поля REST

Поля относятся к выбранной операции; обязательность уточняется условием и минимальным примером. [] — элемент массива.

Опции Make и преобразование в REST

Это справочник выбора в Make; имена интерфейса не всегда совпадают с REST. Поля v1*/v2*, text* и sample* переводятся как описано выше. Вложенные условия относятся к интерфейсу Make.

Ответ и границы проверки

HTTP-ответ с JSON провайдера {code:200,data:{taskId}}; проверяйте code и msg отдельно от статуса HTTP.

Recraft: завершение определяется data.state=success|fail. Цикл Make проверяет другие поля и может продолжать опрос после завершения; прямой REST-клиент должен проверять state.

SUFLER

videoUrl обязателен. Автораспознавание: не передавайте subtitles; transcriptionEngine выбирает whisper/xai_grok_transcribe/gemini/local_whisper/elevenlabs_scribe. Ручной режим: subtitles[] с text,startTime,endTime; 0 ≤ startTime < endTime. words[] использует word,start,end, без перекрытия и внутри реплики. До 500 реплик. Make v1*/v2* — имена формы, REST принимает templateId,fontSize,color,positionX и др. Для v2 ручные настройки требуют presetOverrideMode=manual. Для перевода — translateTo и при необходимости dualLanguage. outputMode: burn/srt/vtt/ass/burn+srt/burn+vtt. v1 использует highlightMode; v2 — renderMode и emphasisMode.

Операции и минимальные JSON-запросы

Каждый пример ниже задаёт полный JSON для указанного POST; замените URL/ID собственными значениями. Опции поля operation или режима выбирают разные функции, а не разные модели генерации. Статус «источник» означает проверку кода без проверки работающего API и полного цикла выполнения; «блокировано» — известное ограничение.

curl --fail-with-body "$FRANKLAB_ORIGIN/franklab/api/franklab/jobs/subtitles" \
  -H "Authorization: Bearer $FRANKLAB_KEY" \
  -H "Content-Type: application/json" \
  --data '{"videoUrl":"https://example.com/synthetic.mp4","captionEngine":"v1","subtitles":[{"text":"Synthetic test","startTime":0,"endTime":1}],"outputMode":"burn"}'

Поля REST

Поля относятся к выбранной операции; обязательность уточняется условием и минимальным примером. [] — элемент массива.

Опции Make и преобразование в REST

Это справочник выбора в Make; имена интерфейса не всегда совпадают с REST. Поля v1*/v2*, text* и sample* переводятся как описано выше. Вложенные условия относятся к интерфейсу Make.

Общие настройки пресетов v2 приведены один раз ниже. «Все 24» означает все значения v2TemplateId из таблицы выше; дополнительные условия в строке также обязательны. v2RevealBaseline доступен для 22 пресетов: всех перечисленных, кроме shorts_pro и creator_hook_v2.

Ответ и границы проверки

HTTP 200 {success:true,data:{taskId,status,final_cost_franks,cost_currency,cost_status,cost_unit}}; опрашивайте статус по полученному taskId.

Результат: downloadUrl/subtitleFileUrl, subtitleCount, transcribedText; для v2 также qualityScore, qualityGateStatus, renderMode, animatedWordCount, highlightedWords, visualQaStatus/visualQaUrl, subtitleDiagnostics. Проверяйте captionWarnings, fontRenderWarning, requestedFont/resolvedAssFont, appliedVideoFilters и ignoredVideoEffects. В Make нормализатор удаляет произвольные поля реплик; при cueStyleOverrideMode=cue сохраняет x/y/fontSize/font/color. В прямом REST передавайте только поля DTO.

REST position: top-left/top-center/top-right/center/bottom-left/bottom-center/bottom-right. Для v2 пользовательские параметры оформления требуют presetOverrideMode=manual. Условия subtitleSourceMode/translationMode/effectsMode/v1*/v2* в справочнике относятся к форме Make, не к полям REST.

Следующий шаг

Выберите одну операцию, загрузите небольшой собственный файл, проверьте доступ и клиентский тариф, затем отправьте один запрос и сохраните его taskId вместе с маршрутом опроса. Для заблокированных функций сначала требуется отдельная проверка или исправление контракта.