# Media Processing API (dvocorp)

> REST API for image and video processing: compression, format conversion,
> resizing, cropping, subtitles and transcription (speech recognition),
> AI-assisted rough cuts, voice cleanup, GIF and thumbnail generation, circular
> video for Telegram video notes, vertical-canvas reframing for TikTok / Reels /
> Shorts, watermarks, EXIF/GPS stripping and multi-GB uploads. Credit-based,
> authenticated with a single API-key header. No FFmpeg or servers to run.

The entire API is two requests: one multipart POST that carries the file plus
what to do with it, then a poll (or a webhook) for the result.

    POST https://mp.dvocorp.com/api/v1/jobs/upload
      header: X-Api-Key: ca_live_...
      form:   file=@video.mp4
              service_slug=clipconvert        # or photoconvert for images
              operation_key=compress
              params={"level":"medium"}       # a JSON string
      -> 201 {"id":"<job_id>","status":"processing"}

    GET  https://mp.dvocorp.com/api/v1/jobs/<job_id>
      -> {"status":"done","result":{"output_url":"https://..."}}

## Documentation

- [Documentation index](https://mp.dvocorp.com/docs/index.html): All guides, plain HTML, no JavaScript required.
- [Quickstart](https://mp.dvocorp.com/docs/quickstart.html): The two requests, with working curl. Start here.
- [AI agent integration](https://mp.dvocorp.com/docs/ai-integration.html): A ready-made prompt that teaches a coding agent this whole API in one paste.
- [Operations catalog](https://mp.dvocorp.com/docs/operations.html): Every operation for video and images, with credit cost and parameters.
- [Recipes](https://mp.dvocorp.com/docs/recipes.html): Goal-to-parameters table — compress a video, add subtitles, make a Telegram video note, and more.
- [Large files](https://mp.dvocorp.com/docs/large-files.html): Uploading and processing files above ~100 MB, up to multi-GB video.
- [Managing jobs](https://mp.dvocorp.com/docs/jobs.html): Status polling, listing, re-running and canceling jobs; billing and refunds.
- [Upload links](https://mp.dvocorp.com/docs/upload-links.html): One-time links so your end users (e.g. a Telegram bot's users) can upload large files without an account.
- [Authentication](https://mp.dvocorp.com/docs/authentication.html): API keys — creating, pausing, deleting, per-key daily caps.
- [Errors](https://mp.dvocorp.com/docs/errors.html): Every status code, what causes it and how to react. Includes rate limits.
- [Developer API page](https://mp.dvocorp.com/docs/api): Interactive version — examples filled in with your own key, plus a downloadable Postman collection.
- [Plain-text API reference](https://mp.dvocorp.com/llms-full.txt): The complete documentation as one text file, for agents that prefer a single fetch.
- [Interactive API explorer](https://mp.dvocorp.com/api/docs): Swagger UI over the live schema.

## Machine-readable

- [OpenAPI specification](https://mp.dvocorp.com/api/openapi.json): Complete OpenAPI schema for every endpoint, generated from the running service.
- [Operation catalog](https://mp.dvocorp.com/api/v1/studio/tools): Public, no auth. Every available operation with its `service_slug`, `operation_key`, accepted media kind, credit cost, ready-made presets and each tunable parameter with type/min/max. This is the source of truth — do not hardcode an operation list.

## What each service does

- `clipconvert` (video): compress, resize, convert (mp4/webm/mov), trim, change fps, speed, rotate, flip, faststart, mute, extract_audio, add_audio (voiceover/music), enhance_voice, gif, thumbnail, cover, subtitles (burn or soft track, with automatic speech recognition), transcribe (srt/vtt/txt/json), auto_edit (cut pauses and filler words), circle (Telegram video note), blur_bg (fit to a vertical canvas), watermark, strip_metadata.
- `photoconvert` (images): resize, compress, convert (webp/avif/jpeg/png), crop, circle (avatar), transform, enhance, social sizes, web_optimize, strip_meta, device_meta (camera EXIF presets), watermark, edit (full pipeline in one pass).

## Notes for integrators

- Auth is one header: `X-Api-Key: ca_live_...`. Keys are created on the Developer API page and read from an env var in your code.
- The audio operations (`extract_audio`, `mute`, `enhance_voice`, `transcribe`) take a **video file** as input, not a bare audio file — they read the audio track out of a video container. A `.mp3`/`.wav`/`.aac` is refused with `400 this operation works on video files — the file you sent looks like audio`. Wrap standalone audio in a video container first.
- Files above ~100 MB bypass the one-call route: upload straight to storage first (`POST /api/v1/uploads` or a presigned PUT), then submit by URL with `POST /api/v1/jobs/api`.
- End users can upload without an account through one-time upload links (`POST /api/v1/upload-sessions/api`) — built for Telegram bots and similar integrations that cannot relay large files themselves.
- Credits are debited at submit and refunded automatically if a job fails or is canceled.
- `429` responses carry `Retry-After` in seconds; honor it.