---
title: "Run a skill on your video"
method: POST
path: "/v1/skills/{id}/run"
tags: ["Skills"]
---

# Run a skill on your video

`POST /v1/skills/{id}/run`

## Request

- Base URL: `https://apihub.co.il`
- URL: `https://apihub.co.il/v1/skills/{id}/run`
- Auth: HTTP bearer

Opens a video-agent run made with the skill's current approved version — the same call for every complete video, ours and creators'. The plan shows production and the skill fee as separate lines; with `max_credits` the plan is approved on its own while the total stays within it, otherwise approve it with `POST /v1/agent/runs/{run}/actions` `{ "action": "approve" }`. Follow it with `GET /v1/agent/runs/{run}`. The skill fee is charged once, only when the video is ready; a failed or cancelled run pays no fee.

**Billing:** production at your rate + the skill's fee · **Rate limit:** 60/min per key

## Path parameters

- `id` string, required

## Request body

- object
  - `media_url` string, uri, required: The video to work on: a public file, or an upload (POST /v1/agent/uploads)
  - `media_name` string, nullable
  - `message` string, nullable: What you want, in your words (optional: the skill knows its job)
  - `locale` 'he' | 'en' | 'uk' | 'null', nullable
  - `max_credits` integer, nullable: Approve the plan without asking while its total (production + the skill fee) stays within this many credits
  - `profile_id` string, nullable: Your agent (GET /v1/agent/profiles): its networks and publishing stay; the style is the skill's
  - `client_key` string, nullable: Your idempotency key: the same key twice returns 409 instead of a second run

## Response `201`

The run (as GET /v1/agent/runs/{run}) and the skill it uses: `skill: { id, version, version_id, name }`

## Other responses

- `400`: invalid_input · footage_is_reference (a copy skill's own video sent as your footage)
- `404`: skill_not_found
- `409`: skill_not_available · skill_not_published · skill_suspended · duplicate_client_key
- `422`: skill_input_length — the video is shorter or longer than the skill takes

---

[API](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai.md) · [All operations](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/llms.txt) · [OpenAPI document](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/revisions/a8caa42835ce?raw)