> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Media skills

> Turn 1–3 public short videos into a skill your agents can follow — built, sampled and saved for you.

A media skill build studies 1–3 public short videos (Instagram Reels or TikTok videos), writes a `SKILL.md` that captures their format, and renders a sample to show it. Every round that finishes is saved as the next version of one of your organization's [skills](/docs/api/skills), so it appears on the Skills page and any agent can use it. Not happy with it? Send feedback and the build runs another round.

A build runs in your organization and bills what it uses to your balance, up to a fixed budget per build. It needs a live key (`sk_live_…`); a test key is refused with `forbidden`.

Your agents can build and revise skills too, with the `build_media_skill` tool: it asks before it starts, runs in the background, and tells the agent the saved skill and its samples when the round is done. The same rules apply — a live organization, in credit, the same budget per build.

## The media skill build object

**id** `string`

Unique id (e.g. `ctp_01H...`).

**object** `string`

Always `media_skill_build`.

**name** `string`

The build's name; the saved skill's slug is made from it.

**state** `string`

`building` while a round runs, `ready` once one has finished, `setup` when none has.

**urls** `string[]`

The links, as accepted.

**rounds** `object[]`

Newest first. Each has `n`, `feedback`, `state` (`queued` → `authoring` → `rendering` → `ready` | `failed`), `skill_md`, `frames`, `samples` (each with a short-lived `url`), `spend_micro_usd`, `error`, `created_at` and `finished_at`.

**skill** `object | null`

`{ id, slug, version }` — the skill the newest finished round was saved as. `null` until the first round is ready.

**spend\_micro\_usd** `integer`

What the build has used so far.

**created\_at** `string`

Creation timestamp.

## Start a build

`POST /v1/media/skills` — scope `agents:write`. With `urls`, it starts a build; with `build_id` and `feedback`, it [revises one](#revise-a-build). An [`Idempotency-Key`](/docs/api/overview#idempotency) header is **required**; a retry with the same key answers the build it already started. Your balance must be above zero (`insufficient_credits`).

**urls** `string[]` *required*

1–3 public reel or video links. Anything else is refused with `validation_failed` on `urls`.

**name** `string`

Up to 80 characters. Defaults to `Reel skill <6 characters of the id>`.

**description** `string`

What the format is for, up to 2000 characters; it becomes the skill's description.

```bash cURL theme={"system"}
curl -fsSL https://api.vetta.sh/v1/media/skills \
  -H "authorization: Bearer sk_live_..." \
  -H "idempotency-key: 3b2e...91" \
  -H "content-type: application/json" \
  -d '{ "urls": ["https://www.instagram.com/reel/DeimezNsQRN/"], "name": "Slow feast" }'
```

The answer is `202` with the build, its first round `queued`.

## Read a build

`GET /v1/media/skills/{id}` — scope `agents:read`. Builds move forward on their own; reading one also moves it forward, so poll this until `state` is `ready`. When a round is ready its skill is already saved: `skill.slug` at `skill.version` (e.g. `media-slow-feast`, version `1`). Its reference frames stay private to your organization: the `SKILL.md` names each one by its [file](/docs/api/files) id (`fil_…`), which your agents can read.

To run the skill as its own channel, install Short Form Social bound to it: `POST /v1/blueprints/installs` with `blueprint: "media"`, `template: "faceless"`, `skill: "<slug>@<version>"`, a new `project` and `expected_revision: 0` ([installs](/docs/api/apps)). Every agent of that install uses the skill, on every later apply too; no other install gets it. An agent that ran the build proposes exactly this install, and a person approves it. After a revision, it proposes re-applying the install already bound to the skill with the new version instead.

If a round cannot be saved it is `failed` (`the skill could not be saved — send a revision to try again`); a revision saves to the same skill. Reading a build moves a round you already started forward, which can start that round's paid author and demo sessions within its cap; it never starts a new round.

## List builds

`GET /v1/media/skills` — scope `agents:read`. Newest first, [paginated](/docs/api/overview#pagination), filtered by `?state=` (`setup`, `building` or `ready`). A list does not move builds forward.

## Revise a build

Send `POST /v1/media/skills` again with the build's id and your feedback instead of `urls`. It runs the next round; when that is ready, it is saved as the next version of the same skill. The same rules apply: an `Idempotency-Key` header is **required** (a retry with the same key answers the round it already started) and your balance must be above zero.

**build\_id** `string` *required*

The build to revise (`ctp_…`).

**feedback** `string` *required*

What to change, 1–4000 characters.

A body carries `urls` or `build_id`, never both (`validation_failed`). A revision while a round is still running is refused with `version_conflict`. Another organization's build is `not_found`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.