02.2 — Integration· 6 min read
REST API.
Upload videos, kick off clip generation, and list generated clips programmatically. JSON in, JSON out — against the same backend that powers the Klyph dashboard.
Note
Scope of the API today.
The endpoints below cover projects, video upload, clip generation, and listing clips. Publishing to social platforms and analytics are not yet exposed — see the roadmap.
§ 1
Base URL
https://app.klyph.ai/apiRequests include your workspace account id. The dashboard shows the account id for every workspace you belong to in settings.
§ 2
Create a project
curl https://app.klyph.ai/api/dev/create-project \
-H "Content-Type: application/json" \
-d '{
"name": "Fall Interviews",
"accountId": "acc_01h..."
}'| Field | Type | Description |
|---|---|---|
| name | string | Display name — slug is derived and made unique per account |
| accountId | string | Target workspace account id |
§ 3
Upload a video
Multipart upload. The file is stored under your workspace bucket and a video record is created with status uploaded.
curl https://app.klyph.ai/api/dev/upload-video \
-F "file=@./interview.mp4" \
-F "account_id=acc_01h..." \
-F "project_id=proj_01h..."| Field | Type | Description |
|---|---|---|
| file | file | The video file (mp4, mov, mkv, webm) |
| account_id | string | Target workspace account id |
| project_id | string | Target project id |
§ 4
Submit for clip generation
Kick off clip generation for an uploaded video. Returns a callId you can poll for the result.
curl https://app.klyph.ai/api/dev/process-video-submit \
-H "Content-Type: application/json" \
-d '{
"videoId": "vid_01h...",
"maxClips": 3,
"minDuration": 30,
"maxDuration": 60,
"aspectRatio": "9:16",
"customInstructions": "prioritize funny moments"
}'| Field | Type | Description |
|---|---|---|
| videoId | string | Id of the uploaded video |
| maxClips | number? | Target number of clips (default 3) |
| minDuration | number? | Minimum clip duration in seconds (default 30) |
| maxDuration | number? | Maximum clip duration in seconds (default 60) |
| aspectRatio | string? | 9:16 | 1:1 | 16:9 |
| customInstructions | string? | Free-form guidance for the clip selector |
§ 5
Poll for the result
# 202 = still running — poll again shortly
# 200 = done, body contains the result payload
# 404 = call not found
curl "https://app.klyph.ai/api/dev/process-video-result?callId=call_789"§ 6
List clips for a video
{
"clips": [
{
"id": "clip_01h...",
"title": "The trick nobody tells you about...",
"start_seconds": 412.3,
"end_seconds": 454.1,
"aspect_ratio": "9:16",
"status": "ready",
"preview_url": "https://...signed-url..."
}
]
}preview_url is a signed URL valid for one hour.
§ 7
Video summary
Lightweight overview of a video’s processing state — useful for dashboards.
{
"video": { "id": "vid_01h...", "title": "Interview", "status": "ready" },
"counts": { "total": 3, "ready": 2, "draft": 1, "failed": 0 }
}§ 8
Errors
| Field | Type | Description |
|---|---|---|
| 400 bad_request | error | Missing or invalid fields — check the error message |
| 404 not_found | error | Video, project, or call id not found |
| 500 server_error | error | Unexpected failure — safe to retry with backoff |