# KinoPipe – Video Editing for AI Agents (`benign_dogfish/kinopipe-video-editor`) Actor

Run 22 typed video tools for trimming, resizing, compression, subtitles, audio, composition, GIF, and metadata. KinoPipe processes public media URLs, enforces a per-run compute cap, and returns signed download links for AI agents and automation workflows.

- **URL**: https://apify.com/benign\_dogfish/kinopipe-video-editor.md
- **Developed by:** [Nicolas Coutureau](https://apify.com/benign_dogfish) (community)
- **Categories:** AI, Videos, Developer tools
- **Stats:** 2 total users, 1 monthly users, 63.6% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 video processing credits

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## KinoPipe – Video Editing for AI Agents

Run a typed KinoPipe video editing tool from Apify, wait for the asynchronous job, and receive temporary downloadable output URLs in the default dataset.

This Actor is a thin integration layer. Video processing stays on KinoPipe workers; the Actor only validates input, submits the job, polls its status, and records the result.

### Features

- 22 bounded tools for trimming, resizing, compression, conversion, subtitles, audio, composition, GIF, metadata, and split workflows.
- One to six public or signed HTTP(S) media inputs.
- Safe retries using a KinoPipe idempotency key derived from the Apify run ID.
- A hard per-run credit ceiling with reservation and automatic refund of unused KinoPipe credits.
- Usage-based pay-per-event support through the `video-credit` event.
- No user-supplied KinoPipe credential. The integration key remains an Actor secret.
- The KinoPipe Bearer token is only sent to the configured KinoPipe API origin.

### Input

| Field | Required | Description |
| --- | --- | --- |
| `tool` | Yes | A KinoPipe tool slug such as `compress-video`, `trim-video`, or `split-video`. |
| `inputs` | Yes | One to six media items. The first item must have `id: "main"`. |
| `options` | No | Tool-specific JSON options. |
| `maxCredits` | No | Hard billing ceiling from 1 to 720 credits. Default: 50. A successful job uses the greater of rounded-up worker seconds or rounded-up 6 MiB output units. |
| `timeoutSeconds` | No | Completion timeout from 30 to 3,600 seconds. Default: 900. |
| `pollIntervalSeconds` | No | Status polling interval from 1 to 15 seconds. Default: 2. |
| `idempotencyKey` | No | Stable retry key. The Apify run ID is used by default. |

Basic example:

```json
{
  "tool": "trim-video",
  "inputs": [
    {
      "id": "main",
      "url": "https://example.com/video.mp4"
    }
  ],
  "options": {
    "start": 2.5,
    "end": 17
  }
}
```

Multi-input example:

```json
{
  "tool": "add-watermark-to-video",
  "inputs": [
    { "id": "main", "url": "https://example.com/video.mp4" },
    { "id": "watermark", "url": "https://example.com/logo.png" }
  ],
  "options": {
    "position": "bottom-right",
    "width": 240,
    "opacity": 0.85
  }
}
```

Additional input IDs used by focused tools:

- `captions` for `add-subtitles-to-video`
- `watermark` for `add-watermark-to-video`
- `pip` for `picture-in-picture-video`
- `music` for `add-music-to-video`
- any unique IDs after `main` for `merge-videos`

See the canonical tool request documentation at <https://kinopipe.com/docs>.

### Output

The Actor writes one dataset item only after the KinoPipe job succeeds:

```json
{
  "tool": "compress-video",
  "jobId": "f7541d5e-12c3-4d5e-8f90-123456789abc",
  "status": "succeeded",
  "statusUrl": "https://kinopipe.com/api/v1/jobs/f7541d5e-12c3-4d5e-8f90-123456789abc",
  "outputUrl": "https://media.example.com/output.mp4?signature=temporary",
  "outputs": [
    {
      "downloadUrl": "https://media.example.com/output.mp4?signature=temporary",
      "filename": "output.mp4",
      "contentType": "video/mp4",
      "byteSize": 1234567
    }
  ],
  "runtimeMs": 8200,
  "consumedCredits": 9,
  "completedAt": "2026-08-25T16:00:00.000Z"
}
```

Download URLs are signed and temporary. Download or copy the finished media promptly.

### Billing behavior

The Actor checks that the run budget can cover the full `maxCredits` ceiling before submitting work. KinoPipe reserves that many internal credits and refunds all unused credits after success. A successful job uses the greater of rounded-up worker seconds or rounded-up 6 MiB output units; the two totals are never added together. The Actor then charges only the credits actually consumed and writes the result to the dataset without a second charge. Failed and canceled jobs do not trigger the `video-credit` event. If the user's spending limit only allows a partial charge, the Actor does not publish the result.

At **$0.01 per credit**, a two-credit completed job costs $0.02 and a ten-credit job costs $0.10. The default 50-credit ceiling limits the variable charge to $0.50; lower `maxCredits` for a tighter limit or raise it for longer edits or larger outputs. The Apify run maximum charge must cover the selected ceiling, but unused capacity is not billed.

Before enabling public monetization in Apify Console:

1. Select **Pay per event**.
2. Add the custom event `video-credit` at **$0.01 per video credit**.
3. Set the synthetic `apify-default-dataset-item` event to zero or remove it to avoid charging twice for the same output.
4. Keep the Actor out of Standby mode and use limited permissions for agentic payment eligibility.
5. Run private pricing tests with representative short, long, single-output, and split-video inputs.

KinoPipe costs vary with media length, tool complexity, and delivered output size, so the Actor bills the measured credit count instead of using a flat per-render price.

### Local development

Requirements: Node.js 22 or newer.

```sh
npm install
npm run check
```

Create `storage/key_value_stores/default/INPUT.json` with an input example, then run:

```sh
KINOPIPE_API_KEY=kp_live_your_private_integration_key \
ACTOR_TEST_PAY_PER_EVENT=true \
npm start
```

Local pay-per-event calls are recorded in the `charging-log` dataset. Never commit the integration API key or place it in Actor input.

### Private Apify deployment checklist

1. Create a dedicated KinoPipe account/API key for the Apify channel so its usage and balance are isolated.
2. Log in with the Apify CLI from this directory.
3. Push the Actor as private.
4. Store `KINOPIPE_API_KEY` as an Apify secret/environment variable. Do not add it to `actor.json`.
5. Optionally set `KINOPIPE_API_BASE_URL`; it defaults to `https://kinopipe.com`.
6. Run one private end-to-end edit and confirm the output, KinoPipe credit debit, and Apify charging log.
7. Configure pricing, identity/payout details, Store copy, and only then publish.

# Actor input Schema

## `tool` (type: `string`):

The typed KinoPipe operation to run.

## `inputs` (type: `array`):

One to six public HTTP(S) media URLs. The first input must have the ID main. Some tools also require captions, watermark, pip, or music.

## `options` (type: `object`):

Tool-specific JSON options. Examples: {"quality":"balanced"}, {"start":2.5,"end":17}, or {"aspect\_ratio":"9:16","fit":"cover"}.

## `maxCredits` (type: `integer`):

Hard ceiling for billable KinoPipe credits across worker time and output size. The Actor verifies that the run budget can cover this ceiling before processing; unused capacity is not charged.

## `timeoutSeconds` (type: `integer`):

Maximum time to wait for KinoPipe to finish before failing this Actor run.

## `pollIntervalSeconds` (type: `integer`):

Delay between KinoPipe status checks.

## `idempotencyKey` (type: `string`):

Optional stable key for safely retrying the same edit. The Apify run ID is used when omitted.

## Actor input object example

```json
{
  "tool": "compress-video",
  "inputs": [
    {
      "id": "main",
      "url": "https://kinopipe.com/demo/before-after/aurora.mp4"
    }
  ],
  "options": {},
  "maxCredits": 50,
  "timeoutSeconds": 900,
  "pollIntervalSeconds": 2
}
```

# Actor output Schema

## `results` (type: `string`):

One dataset item containing the completed job and every generated output.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "inputs": [
        {
            "id": "main",
            "url": "https://kinopipe.com/demo/before-after/aurora.mp4"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("benign_dogfish/kinopipe-video-editor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "inputs": [{
            "id": "main",
            "url": "https://kinopipe.com/demo/before-after/aurora.mp4",
        }] }

# Run the Actor and wait for it to finish
run = client.actor("benign_dogfish/kinopipe-video-editor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "inputs": [
    {
      "id": "main",
      "url": "https://kinopipe.com/demo/before-after/aurora.mp4"
    }
  ]
}' |
apify call benign_dogfish/kinopipe-video-editor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,benign_dogfish/kinopipe-video-editor"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/oSKGe9ZqfeRclWmoP/builds/jExVUfygvgoezorgg/openapi.json