# Video Clipping API for AI Agents: Upload to Receipts

> How an AI agent uploads a video, clips it, publishes after the user confirms and reads 48h and 7d YouTube Shorts receipts via Everpop's API and MCP.

HTML version: https://everpop.app/blog/video-clipping-api-for-ai-agents

Published: 2026-10-01
Updated: 2026-10-01
By Everpop

**Everpop's REST API lets an AI agent run the whole short-video loop on a creator's own file: upload the video, start clips, poll the job, publish to exact connected accounts once the user confirms, then read receipts for eligible YouTube Shorts at 48 hours and 7 days. It needs a Pro or Scale plan and a Bearer key.**

The contract is an [OpenAPI 3.1 spec](https://everpop.app/openapi.json), and [skill.md](https://everpop.app/skill.md) walks an agent through every call.

## What does an agent need before the first API call?

An agent needs an Everpop API key on a [Pro ($49/mo) or Scale (from $149/mo)](https://everpop.app/pricing) account; Free and Starter accounts [can connect, but requests return 402](https://everpop.app/agents). The user creates the key on the API page of the studio, and the agent sends it as `Authorization: Bearer epk_…` on every request, never in a URL.

Keys are Full (read + write), the default, or [Read-only](https://everpop.app/auth.md), which can call every `GET` endpoint and gets 403 `scope` on a write. Example: a reporting agent that reads receipts gets a read-only key, so a bug in it cannot post.

## How does the upload-to-publish loop work, step by step?

The loop is nine requests, from a usage check to receipts:

| Step | Request | Send | Get back |
|---|---|---|---|
| 1 | `GET /api/v1/usage` | nothing | plan, videos remaining |
| 2 | `POST /api/v1/videos/upload` | `filename`, `sizeBytes` | `putUrl`, `key`, `requiredHeaders`, `expectedBytes` |
| 3 | `PUT` to `putUrl` | exactly `expectedBytes`, every `requiredHeaders` entry | success from storage |
| 4 | `POST /api/v1/videos/complete` | `key`, `rightsConfirmed` (the user's answer), `renderMode: "manual"` | `videoId`, `renderMode` |
| 5 | `POST /api/v1/clip` | `sourceVideoId`, options | `jobId`, `clipCountApplied` |
| 6 | `GET /api/v1/jobs/{id}` | nothing | `status`, then clips with `clipId` |
| 7 | `GET /api/v1/publish` | nothing | exact destination ids |
| 8 | `POST /api/v1/publish` | `clipId`, `destinationIds`, `metadata`, after the user's yes | a status per destination |
| 9 | `GET /api/v1/receipts` | optional `cursor` | 48h and 7d numbers for eligible YouTube Shorts |

## How does an agent upload a video file to the API?

An agent requests an exact-size upload slot, PUTs exactly those bytes with every `requiredHeaders` entry (`Content-Type`, `If-None-Match: *`), then finalizes. Accepted files are .mp4, .mov, .webm, .mkv or .m4v, up to 32 GB on Pro and Scale. `POST /api/v1/videos/upload` takes a file up to 5 GB, the most one `PUT` can carry; for a bigger file it answers 413 `file_too_large` with reason `single_put` and a `browserUploadUrl`, where the user uploads it.

`POST /api/v1/videos/complete` takes the slot's `key` and `rightsConfirmed: true`, the user's own answer that they hold the rights, asked and never inferred. On active plans clipping then starts on its own (`autoClipping: true`). An agent that will call `/clip` with its own options sends `renderMode: "manual"`; otherwise the automatic render uses that video's allowance and the later `/clip` uses another.

Example: a retried `PUT` answers 412. The bytes are already stored, since `If-None-Match: *` refuses to overwrite, so [skill.md says](https://everpop.app/skill.md) to call `/videos/complete` with the same key rather than upload again.

## Which clip options can an agent set?

An agent sets clip count, frame, captions and spoken language on `POST /api/v1/clip`; anything omitted falls back to the account's saved choices.

- `clipCount`: 1 to 20, capped by the plan's clips per video (Pro 10, Scale 15). Read `clipCountApplied`.
- `aspectRatio`: `9:16`, `1:1`, `16:9` or `4:5`. `captionsEnabled` switches burned-in captions for this render.
- `language`: the language **spoken** in the video, not the one you want to read.
- An `Idempotency-Key` header stops a retry from starting a second render.

Example: a Bulgarian interview gets `"language": "bg"` for Bulgarian captions, or `null` for English ones. Sending `"en"` tells the recognizer to hear English and leaves the clip nearly caption-less.

Then poll `GET /api/v1/jobs/{id}` until `status` leaves `PENDING` or `PROCESSING`; on `COMPLETED`, each clip carries a `clipId` and a `review` block (quality warnings, hook, captions) to show the user.

## How does an AI agent publish clips to Shorts, Reels and TikTok?

An agent publishes to YouTube Shorts, Instagram Reels, Facebook Reels and TikTok (as an inbox draft) by naming exact connected destination ids, showing the user every account and field, and calling `POST /api/v1/publish` after an explicit yes. `GET /api/v1/publish` lists each account's id, platform and name; there is no publish-to-all.

The request takes `clipId`, `destinationIds` and `metadata` (`title`, `description`, `privacyStatus`). `private` or `unlisted` needs every destination to be YouTube; otherwise the request returns 422 and nothing publishes. `ok: true` means Everpop accepted the request, so the agent checks each `posts[].status` and follows in-flight posts with `GET /api/v1/posts?clipId=` until each is final.

Example: a TikTok destination ends at `DELIVERED`, meaning a ready-to-post draft sits in the account's inbox and going public stays the creator's tap. Hands-free posting needs an autopilot rule the user switched on; without one, this is [review-first posting](/blog/review-before-your-shorts-post-youtube-inauthentic-policy): the agent carries, the human decides.

## How does an agent report results after publishing?

`GET /api/v1/receipts` returns aggregate YouTube Analytics numbers for eligible YouTube Shorts at 48 hours and 7 days: views, average view percentage and subscribers gained, with a token-protected link per Short. Instagram Reels and Facebook Reels publish and TikTok gets inbox drafts, but none of them is measured today.

Example: at 48 hours the 7-day window is still `null`, so the agent checks again later. Pass `nextCursor` back as `?cursor=` for older pages. Why a link beats a screenshot: [receipts versus screenshots](/blog/youtube-analytics-receipts-why-screenshots-lie).

Agencies run the same loop across client channels: [Scale covers 10 YouTube channels, and Pro and Scale include the API, MCP and Campaign Mode](https://everpop.app/ai-clipping-for-agencies). `POST /api/v1/campaigns` creates a campaign, `/campaigns/{id}/attach` adds published posts and `/campaigns/{id}/proof` returns its measured report, with `?csv=1` for a spreadsheet ([skill.md](https://everpop.app/skill.md)).

## Which API errors should an agent handle?

Everpop's API errors carry a stable `code`; branch on it, and treat an unknown code by its HTTP status. From [skill.md](https://everpop.app/skill.md) and [the changelog in openapi.json](https://everpop.app/openapi.json):

| HTTP | `code` | What the agent does |
|---|---|---|
| 401 | `key_missing`, `key_invalid`, `key_expired` | Send the header, or ask for a current key |
| 402 | `subscription`, `plan`, `payment_required` | Tell the user; retrying will not change it |
| 413 | `file_too_large` | Over 32 GB: re-export smaller or trim; with reason `single_put` (over 5 GB), give the user `browserUploadUrl` |
| 422 | `upload_required` | Upload the file; do not retry the clip |
| 429 | `rate_limited`, `queue_capacity` | Wait for `Retry-After`, then resend |
| 429 | `upload_slots` | 3 uploads are open: finalize one, or cancel one and wait out its 15-minute window |
| 429 | `quota_exhausted` | Tell the user the monthly videos are used up |

## Can an agent run the same loop over MCP?

Yes. Everpop's MCP server at `https://everpop.app/api/mcp/mcp` exposes [13 tools](https://everpop.app/agents) over Streamable HTTP for the same loop, from `request_upload` to `list_receipts`. MCP is [an open-source standard for connecting AI applications to external systems](https://modelcontextprotocol.io/docs/getting-started/intro). Clients sign in with OAuth 2.1 + PKCE or the same Bearer key, and `publish_clip` is marked destructive so clients can ask before it runs. Clips started over MCP stay drafts even with Autopilot on. The official MCP Registry [lists it](https://registry.modelcontextprotocol.io/v0/servers?search=everpop) as `app.everpop/everpop`.

Example: in a chat app without file access, the user uploads in the studio or a linked Google Drive folder, and the agent continues from `list_videos`.

## What can't the Everpop API do?

The Everpop API cannot clip a link: Everpop never downloads from YouTube. It does not measure Reels or TikTok posts. And it will not publish to accounts nobody named.

## Claims table

| Claim | Source |
|---|---|
| OpenAPI 3.1, version 1.2.0; destination id, platform and name; per-cause `Retry-After` | https://everpop.app/openapi.json |
| API fields, `renderMode`, 412 retry, `Idempotency-Key`, `privacyStatus`, TikTok `DELIVERED`, `posts?clipId=`, error codes, 413 `single_put` on the upload request, MCP renders stay drafts on Autopilot, receipts, campaigns | https://everpop.app/skill.md |
| Key location, scopes, 401 and 403 codes | https://everpop.app/auth.md |
| Pro and Scale prices with API access; 32 GB files on Pro, Scale includes everything in Pro | https://everpop.app/pricing |
| 402 for Free and Starter; file formats; MCP tools, sign-in, destructive `publish_clip`; autopilot rule; chat-app uploads; no YouTube downloads | https://everpop.app/agents |
| MCP definition | https://modelcontextprotocol.io/docs/getting-started/intro |
| Registry listing | https://registry.modelcontextprotocol.io/v0/servers?search=everpop |
| Scale's 10 channels; API, MCP, Campaign Mode | https://everpop.app/ai-clipping-for-agencies |

## Frequently asked questions

### Is there a video clipping API with an OpenAPI spec for AI agents?

Yes. Everpop's REST API at /api/v1 is described by an OpenAPI 3.1 spec at https://everpop.app/openapi.json, and https://everpop.app/skill.md walks an agent through every call: upload, clip, poll, publish and receipts. Access needs the Pro ($49/mo) or Scale plan; other accounts get HTTP 402.

### Can an AI agent publish clips without asking the user?

Not under Everpop's rules. POST /api/v1/publish needs exact destination ids from GET /api/v1/publish, the final title, description and visibility, and the user's explicit confirmation. There is no publish-to-all, and the MCP tool publish_clip is marked destructive so MCP clients can ask before it runs. Hands-free posting runs through an autopilot rule the user switches on themselves, and clips started over MCP stay drafts even then.

### Can the Everpop API clip a YouTube link?

No. Everpop never downloads from YouTube, and clipping a video that has no uploaded file returns 422 upload_required. The agent uploads the user's own file instead: MP4, MOV, WEBM, MKV or M4V, up to 32 GB on Pro and Scale; one API PUT carries up to 5 GB, and a bigger file goes through the browser uploader.

### What does the language field in POST /api/v1/clip mean?

It names the language spoken in the video. An ISO-639-1 code such as bg keeps captions in that language; null gives English captions from any speech. Sending en for non-English speech leaves the clip nearly caption-less.

### What results can an agent read after publishing?

GET /api/v1/receipts returns views, average view percentage and subscribers gained at 48 hours and 7 days for eligible YouTube Shorts, newest first with cursor pagination. On Pro and Scale, the campaign endpoints group published posts into one measured report, with ?csv=1 for a spreadsheet. Instagram Reels and Facebook Reels publish and TikTok gets inbox drafts, but none of them is measured today.

### Does Everpop have an MCP server as well as a REST API?

Yes. The MCP server at https://everpop.app/api/mcp/mcp runs over Streamable HTTP with 13 tools that cover the same loop, from request_upload to list_receipts. Clients sign in with OAuth 2.1 + PKCE or an Authorization: Bearer epk_… key.

More articles: https://everpop.app/blog