Documentation / API

Kedy.AI API

Turn long-form videos into AIShorts — short, vertical, social-ready clips with optional burned-in subtitles, thumbnails, custom fonts and watermarks. Jobs run asynchronously: POST to start, then poll or receive a webhook on completion.

Overview

The Kedy.AI API exposes a single async pipeline that ingests a source video URL and produces one or more AIShorts. You can either hand-pick a clip range (mode: "manual") or let the model auto-select highlights (mode: "viralshorts").

Jobs are created via POST /v1/aishort/, return a job uuid, and complete asynchronously. Poll status with GET /v1/aishort/<uuid>/ or supply a callback URL to receive a webhook on completion.

Authentication

Every request must include company_uuid and company_secret in the JSON body. Both are issued from your Kedy.AI dashboard.

Treat company_secret like a password. Never embed it in client-side code or commit it to source control.

Base URL

All endpoints are served from:

bash

https://api.kedy.ai

Create an AIShort job

POST /v1/aishort/ — submits a render job. Returns immediately with a job uuid; the render itself happens in the background.

Parameters

Field	Type	Required	Description
company_uuid	string (uuid)	yes	Company identifier.
company_secret	string	yes	Company API secret.
url	string	yes	Public URL of the source video.
mode	"manual" \| "viralshorts"	no	Defaults to `viralshorts`. Manual uses `start`/`end`; viralshorts auto-picks highlights.
lang	string (BCP-47)	no	Source audio language, e.g. `en`, `tr`, `es`.
fps	number	no	Render FPS.
start	number (s)	cond	Clip start in seconds. Manual mode only.
end	number (s)	cond	Clip end in seconds. Manual mode only.
duration	number (s)	no	Convenience: `end = start + duration`.
num_shorts	int	cond	Number of shorts to generate. Viralshorts only.
expected_short_length	number (s)	cond	Target length per short. Viralshorts only.
aishort_hint	string	no	Free-text hint guiding highlight selection.
add_subtitle	bool	no	Burn subtitles into the rendered short.
add_thumbnail	bool	no	Generate a first-frame thumbnail for the rendered short.
font	object	no	`{ mode: "default"\|"custom", type?, url?, size? }`
watermark	object	no	`{ url, position: "left_top"\|"right_top"\|"left_bottom"\|"right_bottom", w (0-1 of frame width), x?, y? }`
callback	string (URL)	no	Webhook called when render completes.

Response

json

{
  "status": "started",
  "uuid": "5b24d51d-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "callback": "https://yourapp.example.com/webhooks/kedy"
}

Poll job status

GET /v1/aishort/<uuid>/ returns the current render progress and, on completion, the export_url.

The trailing slash is required.

bash

curl https://api.kedy.ai/v1/aishort/<JOB_UUID>/

Response:

json

{
  "status": "completed",
  "progress": 100,
  "export_url": "https://cdn.kedy.ai/.../short.mp4"
}

Callback webhook

If you supply a callback URL when creating the job, Kedy.AI will POST the following JSON to that URL once the render reaches a terminal state (COMPLETED or FAILED):

json

{
  "uuid": "5b24d51d-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "progress": 100,
  "export_url": "https://cdn.kedy.ai/.../short.mp4"
}

The webhook fires at most once per job. If multiple shorts were produced, export_url points to the first; a shorts array with all items is included as well. Respond 2xx within 10 seconds — we do not retry.

Example: viralshorts

Auto-pick three ~30s highlights from a long video, with burned-in subtitles.

bash

curl -X POST https://api.kedy.ai/v1/aishort/ \
  -H "Content-Type: application/json" \
  -d '{
    "company_uuid":          "YOUR_COMPANY_UUID",
    "company_secret":        "YOUR_COMPANY_SECRET",
    "mode":                  "viralshorts",
    "url":                   "https://example.com/source.mp4",
    "lang":                  "tr",
    "num_shorts":            2,
    "expected_short_length": 30,
    "add_subtitle":          true,
    "add_thumbnail":         true,
    "font":      {"mode": "custom", "url": "https://example.com/font.ttf", "size": 29},
    "watermark": {"url": "https://example.com/logo.png", "position": "right_top", "w": 0.18},
    "callback":  "https://yourapp.example.com/webhooks/kedy"
  }'

Example: manual clip with watermark

Render a specific clip range with a watermark, thumbnail, hint and completion webhook.

bash

curl -X POST https://api.kedy.ai/v1/aishort/ \
  -H "Content-Type: application/json" \
  -d '{
    "company_uuid": "YOUR_COMPANY_UUID",
    "company_secret": "YOUR_COMPANY_SECRET",
    "url": "https://example.com/source.mp4",
    "lang": "tr",
    "mode": "manual",
    "start": 12.5,
    "end": 42.5,
    "aishort_hint": "focus on the ring sections",
    "add_subtitle": true,
    "add_thumbnail": true,
    "watermark": {
      "url": "https://example.com/logo.png",
      "position": "right_bottom",
      "w": 0.18
    },
    "callback": "https://yourapp.example.com/webhooks/kedy"
  }'

Contact

Need a key or have questions? Request API access or email info@kedy.ai.