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, 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
string
Unique id (e.g.
ctp_01H...).string
Always
media_skill_build.string
The build’s name; the saved skill’s slug is made from it.
string
building while a round runs, ready once one has finished, setup when none has.string[]
The links, as accepted.
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.object | null
{ id, slug, version } — the skill the newest finished round was saved as. null until the first round is ready.integer
What the build has used so far.
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. An Idempotency-Key header is required; a retry with the same key answers the build it already started. Your balance must be above zero (insufficient_credits).
string[]
required
1–3 public reel or video links. Anything else is refused with
validation_failed on urls.string
Up to 80 characters. Defaults to
Reel skill <6 characters of the id>.string
What the format is for, up to 2000 characters; it becomes the skill’s description.
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 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). 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, filtered by ?state= (setup, building or ready). A list does not move builds forward.
Revise a build
SendPOST /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.
string
required
The build to revise (
ctp_…).string
required
What to change, 1–4000 characters.
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.