Utilities and montage

Nine modules: C2PA Signer Profiles, FORSAJ, HOLST, INDEXLIFT, KLEY, OVERLAY, PLASTINKA, SPEKTR and SUFLER. 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 a direct public HTTPS URL to your file, or upload it and use 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. The response also includes data.storedFileId, data.mimeType and data.sizeBytes. URL inputs do not require a stored-file ID. 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. See billing for your utility tariff; Studio estimates apply to Studio operations. C2PA list is free; profile mutations may be billed. Recraft and synchronous INDEXLIFT have their own response formats.

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.

Operations and minimal JSON requests

JSON examples below show complete bodies; rows without a JSON object describe parameters only; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models.

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 result

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

JSON examples below show complete bodies; rows without a JSON object describe parameters only; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models.

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 result

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. HOLST does not accept a custom font in these steps. REST accepts removeBgProvider, alphaMatting, ocrLanguages, metadataEngine and includeGps, but Make communication omits their top-level mapping. See the operation notes below for availability.

Operations and minimal JSON requests

JSON examples below show complete bodies; rows without a JSON object describe parameters only; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models.

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 result

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.

Results for info, read_metadata, ocr are temporarily unavailable through this jobs route. Contact support before using these operations.

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

JSON examples below show complete bodies; rows without a JSON object describe parameters only; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models.

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 result

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 does not reserve funds. Read the report at data.result.data.seo_report and suggestions, when present, at data.result.data.brief_suggestions. On successful completion, cost_status=confirmed and the cost is zero.

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. See the comparison and analysis limitations below.

Operations and minimal JSON requests

JSON examples below show complete bodies; rows without a JSON object describe parameters only; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models.

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 result

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

Results for probe, quality_compare, qc_report, scenes are temporarily unavailable through this jobs route. Contact support before using these operations.

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

JSON examples below show complete bodies; rows without a JSON object describe parameters only; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models.

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 result

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

PLASTINKA

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

JSON examples below show complete bodies; rows without a JSON object describe parameters only; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models.

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 result

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

Results for probe, quality_compare, analyze, fingerprint are temporarily unavailable through this jobs route. Contact support before using these operations.

SPEKTR

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[]. Check the Recraft tariff separately from jobs operations. 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

JSON examples below show complete bodies; rows without a JSON object describe parameters only; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models.

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 result

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

JSON examples below show complete bodies; rows without a JSON object describe parameters only; replace URLs/IDs with your own. Operation/mode selectors choose functions, not generation models.

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 31” means every v2TemplateId value in the table above; each row’s additional conditions also apply. v2RevealBaseline applies to 29 presets: all listed values except shorts_pro and creator_hook_v2.

Response and result

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.

The v2 on-screen position can be changed without manual mode: safeZonePreset (bottom_safe / center / top_safe) and positionX+positionY (0–100, % of the frame) also apply with presetOverrideMode=preset, including sufler_ref_* presets, while the rest of the preset's look stays unchanged. Precedence: positionX/positionY → safeZonePreset → the style's own placement. safeZonePreset moves a style vertically only; the horizontal position stays the style's. Styles with their own position (DAN, ELLA, Viktor) take the vertical bands from the TikTok safe zones. In Make this is the «Положение субтитров» field (v2CaptionPosition); exact coordinates are under «Ручная настройка» → «Размещение на экране» → «Точные координаты». Omitted fields keep the style's placement. 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. If an operation fails, read its error and keep the existing task ID when contacting support.