3. Operations catalog

Every operation is addressed by a service_slug + operation_key pair and takes its input as params.file_url.

The live, always-current list is one public request (no key needed) — this is the same data the panel's catalog renders from:

curl -s https://metaplatho.com/api/v1/studio/tools

Each entry gives you operation_id, service_slug, operation_key, its rate card tariff_class and that card's base credits_per_call, what file kinds it accepts, its tunable parameters (config.fields[], each with key / type / min / max), and its ready-made settings (presets[], each {index, label, params}), the rest of its params (config.api_params[], each {key, default, values}) and example — a {service_slug, operation_key, params} that works as-is.

credits_per_call is what one job costs at submit — the BASE of the operation's rate card (tariff_class), the floor of the job's cost and not its total. A params.operations pipeline is priced at the dearest class of any step in it: addressing a cheap operation while shipping an expensive recipe costs exactly what addressing the expensive one does.

The tariff: you pay for processing time, at one of four rates

Every operation is metered by the worker's clock. The rate depends on the operation's class (the shipped defaults; the live numbers are in GET /api/v1/public/config → billing.tariff_classes):

So a standard job: up to 1 min of processing costs 2, 1–2 min costs 4, 2–3 min costs 6, and never more than 40 for one file. A started minute is a whole minute: 61 seconds is two minutes. Processing time is measured on the worker from the moment it picks your file up — the queue wait is not billed.

Ask before you submit. POST /api/v1/studio/quote (public, no auth, moves no money) prices real files on real tools from what you already know about them:

curl -s -X POST https://metaplatho.com/api/v1/studio/quote -H 'Content-Type: application/json' -d '{
  "files": [{"kind": "video", "duration_sec": 300, "width": 1920, "height": 1080, "size_bytes": 52000000}],
  "operation_ids": [44, 51]
}'

Each tool in the answer carries its tariff_class, the card's three numbers, and per file a likely cost, a max (the cap) and an est_processing_sec; known: false means the length was guessed from the bytes. The studio shows exactly this on every tile the moment a file is dropped.

Nobody knows how long your file will take until a worker has run it, so the flow is:

• at submit you are charged the card's base, and estimated_cost reflects that; the job's tariff_class says which card;
• when the job finishes, the difference is debited and final_cost becomes the real total. Faster than a minute changes nothing — the base is the minimum and is never refunded down.

A job that ends failed or canceled is never charged for time. If it ended within its first 60 seconds of worker time, everything is refunded and final_cost is 0; after that the base is kept (final_cost = base) — the worker ran the file and what it hit was the input. An input over your tier's length limit is always refunded in full. If we cannot measure the time at all, you pay the base and nothing more.

Don't hardcode these numbers — GET /api/v1/public/config returns the four cards under billing.tariff_classes (base_credits, per_minute_credits, max_credits, plus the estimate's work_pct and fixed_sec) and the switch time_tariff_enabled. The historical time_tariff_* fields are the standard card under their old names.

The input ceilings: length and size

The per-file cap bounds your bill; it does not bound our workers. So an input longer than your tier allows is refused, not truncated: the job ends failed, every bonus it took is refunded, and error names the length, the limit and your tier. A file bigger than your tier allows never gets that far: it is refused with 413 when the upload is opened (/uploads/multipart/create, /uploads/multipart/complete, upload links), before a byte is stored.

The length ceiling applies to every operation, not just speech-to-text, and only to media that reports a duration (images are never affected); the size cap applies to every file. Live values are on GET /api/v1/public/config under billing.input_max_minutes and billing.input_max_mb (billing.video_max_mb / video_max_sec carry the largest tier's pair for older clients).

Split a longer recording yourself (trim is a remux — it is cheap and lossless) and submit the parts.

Bulk works the same way, per file. A /studio/batch is charged the base per file at submit and each file's own processing time afterwards, and the length ceiling applies per file too. A file longer than your tier allows stops the batch: the remaining files are canceled, the batch ends failed with the filename in error, and everything not already delivered is refunded, the over-long file included. Files delivered before it stay charged.

Some jobs — compress, resize, convert, watermark, add/strip metadata — exist on both services, once for video and once for images. Those entries share a config.family value. The web studio uses it to show a single button and picks the operation from the file you dropped; over the API you address the two operations separately, as usual, by service_slug + operation_key. The tables below are the shipped baseline — an admin can add or retune operations, so treat /studio/tools as the source of truth.

ClipConvert — video ("service_slug": "clipconvert")

Every operation accepts video; transcribe also takes audio-only files. Class is the rate card the job is priced at — photo 1 (+1/min, cap 5), light 1 (+1/min, cap 10), standard 2 (+2/min, cap 40), speech 5 (+3/min, cap 60) at the time of writing. The base debited at submit is the card's base_credits; the live number per operation is credits_per_call in GET /api/v1/studio/tools, the cards themselves in GET /api/v1/public/config → billing.tariff_classes. Two operations change class with their params: subtitles with your own text, cues or a file is standard (light with mode: "embed"), and auto_edit with cuts is standard — no speech is recognised in either case.

Fit into a size: compress + max_mb. The output comes out no bigger than max_mb megabytes (1 MB = 1 048 576 bytes) in ONE pass — the video bitrate is capped from the duration ((max_mb·8192·0.95 / seconds) − audio), the quality setting still applies below the cap, and if the cap falls under ~1.5 Mbit/s the video steps down to 720p. {"max_mb": 49} fits a Telegram bot's 50 MB upload. Too small a target for the length fails before any work with max_mb 1 is too small for a 600-second video — at least 19.0 MB. result.body.size_target reports {max_mb, size_mb, met, video_kbps_cap, audio_kbps, downscaled_to_720p}.

Which video operations re-encode (and which don't)

An operation that changes no pixels is a remux: the picture is copied packet for packet instead of being re-encoded. It comes back in seconds instead of minutes, and it is bit-identical — no quality loss, no bitrate change.

Frame rate on re-encodes. A re-encode keeps the source frame rate up to 60 fps; faster footage (120/240 fps slow-motion from a phone) comes out at 60 fps — the result reports fps_capped_from. The Business plan has no cap. An explicit fps operation always wins, and a remux keeps the original rate.

Input resolution. Video up to 4K (3840×2160, either orientation) on every plan; Pro and Business take up to 8K (8192×4320 — GoPro 5.3K, DJI, 8K phones, 5K screen recordings). Larger input fails with video too large. Re-encodes of big inputs come out web-sized either way.

Two consequences worth knowing:

• trim accuracy. precise: true (the default) re-encodes so the cut lands exactly on start. precise: false cuts on the nearest keyframe at or before start and copies — near-instant, but the clip can begin up to a few seconds early. A trim from 0 always takes the fast path; the flag only matters for a cut from mid-video.
• Resolution. A re-encode is capped at 1080p. A remux is not — the video is passed through exactly as you sent it, 4K included. Ask for a smaller file explicitly with resize or compress.

The finished job reports which path actually ran at result.body.encode_mode — one of remux, video_copy, audio_copy, encode.

PhotoConvert — images ("service_slug": "photoconvert")

Every operation accepts image.

device_meta presets: iphone, iphone_15, iphone_15_pro_max, iphone_16, iphone_16_pro, iphone_16_pro_max, samsung_galaxy_s24, samsung_galaxy_s24_ultra, samsung_galaxy_s25_ultra, google_pixel_8_pro, google_pixel_9_pro, xiaomi_14_ultra, oneplus_12, sony_xperia_1_vi, huawei_p60_pro, sony_a7_iv, canon_eos_r5, canon_eos_r6_mark_ii, nikon_z8, fujifilm_x_t5.

Send the params. An image operation whose params say nothing to do (watermark with no text and no logo, edit with no pipeline) is rejected with an error — it is never accepted, billed, and answered with your own file back.

There is no separate audio service. Audio work is done by the ClipConvert operations: transcribe takes an audio-only file directly (MP3, WAV, M4A, OGG/Opus, FLAC — its accepts is ["video", "audio"]); extract_audio, mute and enhance_voice read the audio track out of a video and refuse a bare .mp3/.wav with 400 this operation works on video files — the file you sent looks like audio.

DocConvert — PDF ("service_slug": "docconvert")

PDF in and out. merge_pdfs and images_to_pdf take several files as one job — send them in order as repeated files fields (or params.file_urls on /jobs/api); everything else takes one PDF. Every result is a download (Content-Disposition: attachment).

pages picks pages, 1-based: "1-3,5", "2-" (to the end), "last"; empty = all. One page from pdf_to_images comes back as a picture, several as a ZIP of page-001.jpg, … (result.outputs[0].contains lists them).

Several photos → one PDF (the Telegram "album → PDF" case):

curl -s https://metaplatho.com/api/v1/jobs/upload -H 'X-Api-Key: ca_live_...' \
  -F '[email protected]' -F '[email protected]' -F '[email protected]' \
  -F 'service_slug=docconvert' -F 'operation_key=images_to_pdf' \
  -F 'params={"page_size": "a4", "margin_mm": 10}'

Bigger than ~100 MB in total? Upload each file first (POST /api/v1/uploads), then send the URLs in order:

{ "service_slug": "docconvert", "operation_key": "merge_pdfs",
  "params": { "file_urls": ["https://.../a.pdf", "https://.../b.pdf"] } }

Limits and errors:

• one job takes up to 30 files by default (an admin setting; 400 too many files for one job — up to N); one job is one charge however many files;
• file_urls must be files uploaded through this site (400 file_urls must be files uploaded through this site); each one is kind-checked (400 … file 2 looks like image);
• a single-file operation refuses file_urls (400 'compress_pdf' takes one file — send file_url, not file_urls);
• a password-protected PDF fails with this PDF is password-protected — unlock it first; a page range outside the document names the valid range;
• pdf_to_text reads the PDF's text layer — a scan without one fails with this PDF has no text layer (a scan?). There is no OCR.