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:

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

Multi-input example:

{
  "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:

{
  "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.

npm install
npm run check

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

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.