Utilities and montage

Nine modules: C2PA Signer Profiles, FORSAJ, HOLST, INDEXLIFT, KLEY, OVERLAY, PLASTINKA, SPEKTR and SUFLER. Contracts were checked against source on 8 September 2026; access depends on your account and the selected operation.

Connection and upload

Keep your API key in the FRANKLAB_KEY environment variable. Examples use origin https://apergrex.ru; all paths below already include /franklab/api. The repeated franklab in /franklab/api/franklab/jobs is required. SPEKTR/Recraft uses X-API-Key; other examples use Authorization: Bearer. Do not supply 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"

Use upload response data.url to replace https://example.com/synthetic.* in examples; those URLs are placeholders, not downloadable media. Maximum 150 MiB, source retention 7 days. 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. Upload does not convert formats. URLs must be server-accessible; private/local URLs and prohibited redirects are rejected. Save completed outputs before expiresAt when provided.

Connection check: GET /franklab/api/franklab/integrations/text-sticker/auth/stats with an API key. SPEKTR Make reads GET /franklab/api/v1/images/omni-image?pageNum=1&pageSize=1. This reads history/checks authentication; it does not test generation.

Status, output and billing

A successful submission returns HTTP 200 and success:true, which does not mean the output is ready. Store data.taskId; poll the matching route every 5 seconds until data.status=completed or failed. queued and processing are non-terminal. Set a finite deadline; resume reading the existing ID after a timeout. Do not automatically repeat POST after an ambiguous network error.

Jobs expose final_cost_franks, cost_currency=FRANK, cost_status and cost_unit. With cost_status=reserved, the amount is reserved; final is settled, refunded is refunded, and unavailable means no reliable price. Frank is an internal accounting unit, not a currency. A missing field does not mean zero cost. The server checks tariff and capability access. No separate generic utility REST estimate is confirmed; Studio estimate is not a universal utility quote. C2PA list is free in source; profile mutations may be billed. Recraft passthrough and synchronous INDEXLIFT do not establish this settlement contract.

HTTP 400 usually means invalid parameters or combinations; 401 means authentication; 404 means missing resource; 429 means rate limiting. For 5xx/provider errors, reconcile the existing task before resubmission. success:true with data.status=failed is still failure. Diagnostic operations may return metadataReport/metrics/qcReport without a file; availability is qualified separately.

Content Credentials (C2PA)

Supporting jobs accept c2paSigningMode=off|franklab|user_profile, c2paSignerProfileId for user_profile, and contentOrigin=not_declared|human_edited|ai_assisted|ai_generated|human_created|camera_captured. Optional strings: humanAuthorName, humanAuthorUrl, reviewedBy, reviewedAt, reviewMethod, c2paActionDescription, c2paDisclosure. sourceMaterialUrls and originalEvidenceUrls each allow up to 10 public HTTPS URLs. Restricted human_created/camera_captured claims require an active permitting profile and evidence. Request verifiedIncomingC2paIngredient is not proof: the server verifies the result. Signing is separate from trusted-chain validation: inspect c2paStatus, c2paSigned, c2paCryptographicallyValid, c2paTrustedChainValid, c2paCawgIdentityPresent, c2paPublicVerifierRecognized, c2paManifestUrl and c2paVerificationReport. OVERLAY make/jobs DTO does not declare C2PA fields.

C2PA Signer Profiles

Listing returns active partner profiles without PEM secrets. Creation and rotation take your certificate/key; generate_self_signed creates a self-signed profile. trustLevel=trusted is rejected here. Rotation creates a new version; keep profile IDs distinct. Revocation changes profile validity. No credential mutation was tested.

Operations and minimal JSON requests

Each example below is the complete JSON for its POST; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models. “source” means source-checked without live/E2E; “blocked” marks a known limitation.

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

REST fields

Fields apply to the selected operation; required conditions and the minimal example define usage. [] denotes array items.

Make options and REST conversion

This is the Make selection reference; form names can differ from REST. Convert v1*/v2*, text* and sample* fields as described above. Nested conditions describe the Make form.

Response and verification limits

HTTP 200 {success:true,data:PROFILE[]}; profileId,id,label,status,trustLevel,allowRestrictedOriginClaims,version,profileGroupId,createdAt,updatedAt,rotatedAt,revokedAt; no PEM returned.

For rotation REST accepts optional allowRestrictedOriginClaims; omission inherits the previous value. Current Make communication does not forward this control for rotate_from_pem.

FORSAJ

video_speed posts videoUrl and speed to jobs/video-speed. audio_speed puts the audio URL in videoUrl and sends operation=speed to jobs/audio. speed: 0.25–4. audioBitrate is a string from 8k to 320k; replace the Make custom choice with the actual bitrate. Do not send mode to REST. Video duration may describe the source; inspect the output media.

Operations and minimal JSON requests

Each example below is the complete JSON for its POST; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models. “source” means source-checked without live/E2E; “blocked” marks a known limitation.

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 fields

Fields apply to the selected operation; required conditions and the minimal example define usage. [] denotes array items.

Make options and REST conversion

This is the Make selection reference; form names can differ from REST. Convert v1*/v2*, text* and sample* fields as described above. Nested conditions describe the Make form.

Response and verification limits

HTTP 200 {success:true,data:{taskId,status,final_cost_franks,cost_currency,cost_status,cost_unit}}; poll the returned taskId.

HOLST

Supply imageUrl and either operation or steps (up to 20 entries, each with op). outputFormat: jpeg/jpg/png/webp/avif/gif; outputQuality: 1–100. The current top-level DTO strips several Make fields: watermarkPosition/Opacity/Scale, textPosition/fontSize/color/font, brightness/saturation/hue/contrast/gamma, imageUrls/columns/gap/background. For watermark, text, adjust and collage use steps with position/opacity/scale, content/fontSize/color, brightness and imageUrls/columns/gap respectively. Even ImageStepDto has no font: HOLST font selection is unverified. REST accepts removeBgProvider, alphaMatting, ocrLanguages, metadataEngine and includeGps, but Make communication omits their top-level mapping. OCR/remove_bg/strip_gps/read_metadata depend on worker capabilities; info/read_metadata may be blocked by required output-file inventory checks.

Operations and minimal JSON requests

Each example below is the complete JSON for its POST; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models. “source” means source-checked without live/E2E; “blocked” marks a known limitation.

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 fields

Fields apply to the selected operation; required conditions and the minimal example define usage. [] denotes array items.

Make options and REST conversion

This is the Make selection reference; form names can differ from REST. Convert v1*/v2*, text* and sample* fields as described above. Nested conditions describe the Make form.

Response and verification limits

HTTP 200 {success:true,data:{taskId,status,final_cost_franks,cost_currency,cost_status,cost_unit}}; poll the returned taskId.

Sharpen steps accept sigma; Make flat/jagged are absent from the REST DTO. write_exif steps do not declare imageDescription/copyright/artist: use single operation=write_exif.

Known REST limitation: info, read_metadata, ocr. The worker returns data without a primary file, while task terminalization requires that file. These functions are blocked pending a separate fix; do not use them for a paid trial.

INDEXLIFT

execution_mode=sync calls audit-landing with {url,mode}; async_wait calls audit-landing/async and its dedicated status route. Make pageUrl maps to url. mode: single-page or crawl. Resume with the saved taskId instead of submitting again. idempotency_key is absent from the DTO: use the Idempotency-Key header for async. The synchronous route forwards the SEO service response; it does not establish the media-job billing or response contract.

Operations and minimal JSON requests

Each example below is the complete JSON for its POST; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models. “source” means source-checked without live/E2E; “blocked” marks a known limitation.

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"}'

For async POST add -H "Idempotency-Key: your-unique-request-id". Reuse a key only for the same request.

REST fields

Fields apply to the selected operation; required conditions and the minimal example define usage. [] denotes array items.

Make options and REST conversion

This is the Make selection reference; form names can differ from REST. Convert v1*/v2*, text* and sample* fields as described above. Nested conditions describe the Make form.

Response and verification limits

Sync forwards SEO response; async: {success:true,data:{taskId,task_id,status:"queued",phase,idempotency_key,idempotency_hit,final_cost_franks,cost_currency,cost_status:"reserved",cost_unit}}.

Asynchronous INDEXLIFT uses zeroCost in source and opens no reservation. It is a distinct free execution contract, not a paid media-job; successful execution still needs verification. The parent campaign observed the nested report at data.result.data.seo_report on 8 September 2026; data.result preserves the SEO service envelope. Read suggestions at data.result.data.brief_suggestions when present. Make currently reads top-level body.data.seo_report, which can omit this result. Async successful cost_status is confirmed with zero cost, not the ordinary JobsFacade final.

KLEY

operation selects the route: speed → video-speed; subtitles → subtitles; overlay/image_on_video → overlay; all others → montage. concat accepts videos[] with url and the transition to the next clip; transition fields on the last item are ignored. transitionSoundMode=none/auto/manual; manual requires transitionSoundPreset, volume 0–1.5. Do not send a top-level transitionType string. slideshow requires at least 2 images; slideTransitionDuration must be less than slideDuration. quality_compare requires referenceVideoUrl. Analysis/comparison operations do not guarantee downloadUrl and need separate execution verification.

Operations and minimal JSON requests

Each example below is the complete JSON for its POST; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models. “source” means source-checked without live/E2E; “blocked” marks a known limitation.

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 fields

Fields apply to the selected operation; required conditions and the minimal example define usage. [] denotes array items.

Make options and REST conversion

This is the Make selection reference; form names can differ from REST. Convert v1*/v2*, text* and sample* fields as described above. Nested conditions describe the Make form.

Response and verification limits

HTTP 200 {success:true,data:{taskId,status,final_cost_franks,cost_currency,cost_status,cost_unit}}; poll the returned taskId.

Known REST limitation: probe, quality_compare, qc_report, scenes. The worker returns data without a primary file, while task terminalization requires that file. These functions are blocked pending a separate fix; do not use them for a paid trial.

OVERLAY

Creation and polling use make/jobs. The artifact URL is data.result.downloadUrl. overlays has up to 20 objects: type=text/sticker/animated_sticker/emoji/watermark with type-specific fields. Use IDs from the lookup routes. Text layers use content; watermark layers use imageUrl. platform and configId control placement.

Operations and minimal JSON requests

Each example below is the complete JSON for its POST; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models. “source” means source-checked without live/E2E; “blocked” marks a known limitation.

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 fields

Fields apply to the selected operation; required conditions and the minimal example define usage. [] denotes array items.

Make options and REST conversion

This is the Make selection reference; form names can differ from REST. Convert v1*/v2*, text* and sample* fields as described above. Nested conditions describe the Make form.

Response and verification limits

HTTP 200 {success:true,data:{taskId,status,final_cost_franks,cost_currency,cost_status,cost_unit}}; poll the returned taskId.

PLASTINKA

The 8 September 2026 WAV trim check returned an audio-only MP4, but its codec could not be decoded by the local verification tools. Do not assume the returned container is browser-compatible; verify playback for your input format. Other audio operations were not tested by this example.

For audio processing, the source audio URL is named videoUrl. overlay/replace/fit also need audioUrl or sampleId; Make apply_sample becomes operation=sampleOperation (overlay/replace). merge uses audioUrls[] plus videoUrl equal to the first URL. save_sample returns a resource id, not a task: JSON {name,sampleUrl} or multipart name+sampleFile, exactly one source, up to 50 MiB, mp3/wav/aac/m4a/ogg/flac. sampleEndTime must exceed sampleStartTime. Make exposes sampleSourceMode=file but sends JSON without sampleFile; use direct multipart REST.

Operations and minimal JSON requests

Each example below is the complete JSON for its POST; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models. “source” means source-checked without live/E2E; “blocked” marks a known limitation.

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 fields

Fields apply to the selected operation; required conditions and the minimal example define usage. [] denotes array items.

Make options and REST conversion

This is the Make selection reference; form names can differ from REST. Convert v1*/v2*, text* and sample* fields as described above. Nested conditions describe the Make form.

Response and verification limits

HTTP 200 {success:true,data:{id,name,sourceUrl,mimeType,format,durationMs,clipStartTime,clipEndTime,isSystem,createdAt}}; no task polling.

Known REST limitation: probe, quality_compare, analyze, fingerprint. The worker returns data without a primary file, while task terminalization requires that file. These functions are blocked pending a separate fix; do not use them for a paid trial.

SPEKTR

The 8 September 2026 waveform check failed during processing and its reservation was fully refunded. This result does not establish availability of the other SPEKTR operations.

background_remove uses X-API-Key and Recraft {model:"recraft/remove-background",input:{image:URL}}. Provider envelope: code/data.taskId; status is data.state; results are JSON.parse(data.resultJson).resultUrls[]. This is passthrough without confirmed FrankLab customer settlement. Other operations use Bearer and jobs. waveform maps Make audioUrl → videoUrl; video_round → operation=round; video_remove_bg → operation=remove_bg. Bria image replacement requires exactly one of prompt/refImages; erase_by_text needs objectName; lifestyle needs sceneDescription. Bria video erase over 5 seconds requires autoTrim=true; the backend verifies duration. Make task_id resume may choose Recraft polling for jobs; REST clients must retain the polling route with the ID.

Operations and minimal JSON requests

Each example below is the complete JSON for its POST; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models. “source” means source-checked without live/E2E; “blocked” marks a known limitation.

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 fields

Fields apply to the selected operation; required conditions and the minimal example define usage. [] denotes array items.

Make options and REST conversion

This is the Make selection reference; form names can differ from REST. Convert v1*/v2*, text* and sample* fields as described above. Nested conditions describe the Make form.

Response and verification limits

HTTP response with provider JSON {code:200,data:{taskId}}; inspect code and msg separately from HTTP status.

Recraft completes on data.state=success|fail. The Make repeat condition checks other fields and can continue polling after completion; direct REST clients must check state.

SUFLER

videoUrl is required. Automatic transcription: omit subtitles; transcriptionEngine selects whisper/xai_grok_transcribe/gemini/local_whisper/elevenlabs_scribe. Manual captions use subtitles[] with text,startTime,endTime; 0 ≤ startTime < endTime. Optional words[] uses word,start,end, non-overlapping and inside its cue. Maximum 500 cues. Make v1*/v2* are form names; REST uses templateId,fontSize,color,positionX etc. v2 manual overrides require presetOverrideMode=manual. Translation uses translateTo and optional dualLanguage. outputMode: burn/srt/vtt/ass/burn+srt/burn+vtt. v1 uses highlightMode; v2 uses renderMode and emphasisMode.

Operations and minimal JSON requests

Each example below is the complete JSON for its POST; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models. “source” means source-checked without live/E2E; “blocked” marks a known limitation.

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 fields

Fields apply to the selected operation; required conditions and the minimal example define usage. [] denotes array items.

Make options and REST conversion

This is the Make selection reference; form names can differ from REST. Convert v1*/v2*, text* and sample* fields as described above. Nested conditions describe the Make form.

Shared v2 preset settings are listed once below. “All 24” means every v2TemplateId value in the table above; each row’s additional conditions also apply. v2RevealBaseline applies to 22 presets: all listed values except shorts_pro and creator_hook_v2.

Response and verification limits

HTTP 200 {success:true,data:{taskId,status,final_cost_franks,cost_currency,cost_status,cost_unit}}; poll the returned taskId.

Results: downloadUrl/subtitleFileUrl, subtitleCount, transcribedText; v2 also reports qualityScore, qualityGateStatus, renderMode, animatedWordCount, highlightedWords, visualQaStatus/visualQaUrl and subtitleDiagnostics. Inspect captionWarnings, fontRenderWarning, requestedFont/resolvedAssFont, appliedVideoFilters and ignoredVideoEffects. Make cue normalization removes arbitrary fields; cueStyleOverrideMode=cue retains x/y/fontSize/font/color. For direct REST send DTO fields only.

REST position: top-left/top-center/top-right/center/bottom-left/bottom-center/bottom-right. v2 custom visual settings require presetOverrideMode=manual. Conditions using subtitleSourceMode/translationMode/effectsMode/v1*/v2* in the reference describe the Make form, not REST fields.

Next step

Choose one operation, upload a small owned file, verify access and your customer tariff, then submit once and retain the taskId with its polling route. Blocked functions need a separate contract verification or fix first.