Integrate AI-powered ad analysis and video generation into your own product. The Partner API gives you programmatic access to Knightvision's full feature set.
All requests and responses use JSON. The API is versioned — the current version is v1.
Base URL: https://knightvision.tech
All requests require an API key in the Authorization header:
Authorization: Bearer kv_partner_<your_api_key>
| Status | Response |
|---|---|
| 401 | {"error": "Missing or invalid Authorization header"} |
| 401 | {"error": "Invalid API key"} |
| 403 | {"error": "API key deactivated"} |
Every successful response includes a unique request_id field for debugging.
The API uses URL-based versioning (/api/v1/...). The current version is v1 and is considered stable. Breaking changes will only be introduced in a new version with advance notice. Non-breaking additions (new response fields, new optional parameters) may be added to v1 at any time.
Your account has a credit pool. Each API call that performs work deducts credits. Check your balance anytime via GET /api/v1/partner/credits.
| Action | Credits |
|---|---|
| Ad Analysis | 50 |
| Video: sora-2 (10s) | 22 |
| Video: sora-2 (15s) | 25 |
| Video: sora-2-pro (15s) | 154 |
| Video: sora-2-pro (25s) | 175 |
| Video: kling-v3 / kling-o3 (per second, 720p) | 10/s |
| Video: kling-v3 / kling-o3 (per second, 1080p) | 13/s |
| Character Creation | 22 |
| Character Finalize | 3 |
Rate limits are per API key, per endpoint.
| Endpoint | Limit |
|---|---|
POST /analyze | 20/min |
GET /status/<job_id> | 60/min |
GET /credits | 30/min |
POST /generate-video | 5/min |
GET /video-status/<job_id> | 60/min |
GET /videos | 20/min |
GET/POST /characters | 20/min |
GET /characters/<id> | 30/min |
POST /characters/<id>/finalize | 10/min |
When rate limited you receive HTTP 429. Wait at least 10 seconds before retrying.
Timestamps are returned in UTC, formatted as YYYY-MM-DD HH:MM:SS.
Video URLs returned in responses are permanent and do not expire. You may download them at any time or link to them directly.
Idempotency: Submitting the same request twice will create two separate jobs and deduct credits twice. To avoid duplicate charges, check the response for a job_id before retrying. If your request timed out, check /videos or /status to see if the job was already created.
Async operations: Ad analysis and video generation are asynchronous. Submit a request, receive a job_id, then poll the corresponding status endpoint. We recommend polling every 3-5 seconds.
Analyze a Facebook or Instagram ad. Submit here, then poll /status/<job_id>.
{
"url": "https://www.facebook.com/ads/library/?id=123456789"
}| Field | Type | Required | Description |
|---|---|---|---|
url | string | yes | Facebook/Instagram ad URL or numeric ad ID |
Allowed domains: facebook.com, www.facebook.com, m.facebook.com, instagram.com, www.instagram.com, tiktok.com, www.tiktok.com, vm.tiktok.com
{
"request_id": "a1b2c3d4e5f6",
"job_id": "20260323_141500_abc123",
"status": "queued",
"credits_used": 50,
"credits_remaining": 950
}| Status | Error |
|---|---|
| 400 | "Request body must be JSON" |
| 400 | "Please provide a URL" |
| 400 | "Please provide a valid Facebook, Instagram, or TikTok URL" |
| 402 | "Insufficient credits" |
curl -X POST https://knightvision.tech/api/v1/partner/analyze \
-H "Authorization: Bearer kv_partner_your_key_here" \
-H "Content-Type: application/json" \
-d '{"url": "https://www.facebook.com/ads/library/?id=123456789"}'Poll until status is complete or error.
{
"request_id": "a1b2c3d4e5f6",
"job_id": "20260323_141500_abc123",
"status": "downloading",
"message": "Downloading ad from Facebook..."
}Possible status values: queued, downloading, extracting_frames, transcribing, analyzing
{
"request_id": "a1b2c3d4e5f6",
"job_id": "20260323_141500_abc123",
"status": "complete",
"result": {
"summary": "Brief summary of the ad",
"transcription": "Full audio transcription",
"analysis": "Detailed AI analysis of the ad",
"ugc_script": "Generated UGC script based on the ad"
}
}| Status | Error |
|---|---|
| 400 | "Invalid job ID" |
| 404 | "Not found" / "Job not found" |
curl https://knightvision.tech/api/v1/partner/status/20260323_141500_abc123 \ -H "Authorization: Bearer kv_partner_your_key_here"
{
"request_id": "a1b2c3d4e5f6",
"credits_remaining": 950,
"credit_cost_per_analysis": 50,
"costs": {
"analysis": 50,
"video_sora2_10s": 22,
"video_sora2_15s": 25,
"video_sora2pro_15s": 154,
"video_sora2pro_25s": 175,
"video_kling_per_second_720p": 10,
"video_kling_per_second_1080p": 13,
"character_creation": 22,
"character_finalize": 3
}
}curl https://knightvision.tech/api/v1/partner/credits \ -H "Authorization: Bearer kv_partner_your_key_here"
Generate an AI video. Poll /video-status/<job_id> for results.
{
"prompt": "A person walking through a futuristic city",
"model": "sora-2",
"duration": 10,
"aspect_ratio": "9:16"
}| Field | Type | Required | Default | Description |
|---|---|---|---|---|
prompt | string | yes | — | Video description, max 2000 chars |
model | string | no | sora-2 | See models below |
duration | integer | no | 10 | Seconds (valid values depend on model) |
aspect_ratio | string | no | 9:16 | 9:16, 16:9, or 1:1 |
| Model | Valid Durations | Credits |
|---|---|---|
sora-2 | 10, 15 | 22 (10s), 25 (15s) |
sora-2-pro | 15, 25 | 154 (15s), 175 (25s) |
kling-v3-text-to-video | any | 10/s (720p), 13/s (1080p) |
kling-o3-text-to-video | any | 10/s (720p), 13/s (1080p) |
{
"request_id": "a1b2c3d4e5f6",
"job_id": "sora_20260323_141500_abc123",
"status": "queued",
"credits_used": 22,
"credits_remaining": 928
}| Status | Error |
|---|---|
| 400 | "Please provide a prompt" / "Prompt must be 2000 characters or less" |
| 400 | "Invalid model" / "Invalid duration" / "Invalid aspect_ratio" |
| 402 | "Insufficient credits" |
| 500 | "Video generation not available" |
curl -X POST https://knightvision.tech/api/v1/partner/generate-video \
-H "Authorization: Bearer kv_partner_your_key_here" \
-H "Content-Type: application/json" \
-d '{"prompt": "A person walking through a futuristic city", "model": "sora-2", "duration": 10}'Poll until status is complete or error.
{
"request_id": "a1b2c3d4e5f6",
"job_id": "sora_20260323_141500_abc123",
"status": "complete",
"video_url": "https://knightvision.tech/static/videos/sora_20260323_141500_abc123.mp4",
"duration": 10
}curl https://knightvision.tech/api/v1/partner/video-status/sora_20260323_141500_abc123 \ -H "Authorization: Bearer kv_partner_your_key_here"
List your generated videos, newest first. Optional ?limit=N (default 20, max 50).
{
"request_id": "a1b2c3d4e5f6",
"videos": [
{
"job_id": "sora_20260323_141500_abc123",
"prompt": "A person walking through a futuristic city",
"model": "sora-2",
"duration": 10,
"aspect_ratio": "9:16",
"credits_used": 22,
"status": "complete",
"video_url": "https://knightvision.tech/static/videos/...",
"created_at": "2026-03-23 14:15:00"
}
]
}curl "https://knightvision.tech/api/v1/partner/videos?limit=10" \ -H "Authorization: Bearer kv_partner_your_key_here"
{
"request_id": "a1b2c3d4e5f6",
"characters": [
{ "id": 42, "name": "Sales Expert", "status": "ready" }
]
}curl https://knightvision.tech/api/v1/partner/characters \ -H "Authorization: Bearer kv_partner_your_key_here"
Create an AI character from a text prompt. Refunded if creation fails.
{
"name": "Sales Expert",
"prompt": "A confident business person in a modern office",
"duration": 10,
"aspect_ratio": "9:16"
}| Field | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | yes | — | Max 50 characters |
prompt | string | yes | — | Max 1000 characters |
duration | integer | no | 10 | Video duration in seconds |
aspect_ratio | string | no | 9:16 | 9:16, 16:9, or 1:1 |
GET /api/v1/partner/characters/<id> every 3-5 seconds until status is "ready" or "failed".{
"request_id": "a1b2c3d4e5f6",
"character_id": 42,
"status": "processing",
"credits_used": 22,
"credits_remaining": 906
}curl -X POST https://knightvision.tech/api/v1/partner/characters \
-H "Authorization: Bearer kv_partner_your_key_here" \
-H "Content-Type: application/json" \
-d '{"name": "Sales Expert", "prompt": "A confident business person in a modern office"}'Get details for a specific character. You can only access characters you created.
{
"request_id": "a1b2c3d4e5f6",
"character": { "id": 42, "name": "Sales Expert", "status": "ready" }
}curl https://knightvision.tech/api/v1/partner/characters/42 \ -H "Authorization: Bearer kv_partner_your_key_here"
Finalize a character for use in video generation. Refunded if finalization fails.
{
"timestamp_start": 1,
"timestamp_end": 4,
"character_prompt": "Person looking into the camera"
}| Field | Type | Default | Description |
|---|---|---|---|
timestamp_start | integer | 1 | Start timestamp for extraction |
timestamp_end | integer | 4 | End timestamp for extraction |
character_prompt | string | "Person looking into the camera" | Pose description |
{
"request_id": "a1b2c3d4e5f6",
"status": "finalizing",
"credits_used": 3,
"credits_remaining": 903
}curl -X POST https://knightvision.tech/api/v1/partner/characters/42/finalize \
-H "Authorization: Bearer kv_partner_your_key_here" \
-H "Content-Type: application/json" \
-d '{"timestamp_start": 1, "timestamp_end": 4}'1. POST /api/v1/partner/analyze → get job_id 2. GET /api/v1/partner/status/<job_id> → poll every 3-5s until "complete" or "error" 3. Read result.summary, result.analysis, result.transcription, result.ugc_script
1. POST /api/v1/partner/generate-video → get job_id 2. GET /api/v1/partner/video-status/<job_id> → poll every 3-5s until "complete" or "error" 3. Download video from video_url
1. POST /api/v1/partner/characters → get character_id 2. GET /api/v1/partner/characters/<id> → poll until status is "ready" 3. POST /api/v1/partner/characters/<id>/finalize → finalize 4. Use character in video generation prompt
The API is currently poll-based only. Webhook support for async job completion notifications is planned for a future release.
All errors return a JSON object with an error field. HTTP status codes:
| Code | Meaning |
|---|---|
| 400 | Bad request (invalid input, missing fields) |
| 401 | Invalid or missing API key |
| 402 | Insufficient credits (includes credits_remaining) |
| 403 | API key deactivated |
| 404 | Resource not found or not owned by your account |
| 429 | Rate limit exceeded (wait at least 10s) |
| 500 | Server-side error |
| 502 | Upstream provider unreachable |
status field in the response body.| Date | Change |
|---|---|
| 2026-03-27 | Added Kling V3 and Kling O3 models for video generation |
| 2026-03-23 | Added character creation and finalization endpoints |
| 2026-03-22 | Initial v1 release: ad analysis, video generation, credit management |
For integration help, API key requests, or bug reports, contact us at partner@knightvision.tech.