Knightvision Partner API Reference

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

Contents

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer kv_partner_<your_api_key>
StatusResponse
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.


Versioning

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.


Credits

Your account has a credit pool. Each API call that performs work deducts credits. Check your balance anytime via GET /api/v1/partner/credits.

ActionCredits
Ad Analysis50
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 Creation22
Character Finalize3
If a video or character creation fails on our side, credits are automatically refunded.

Rate Limits

Rate limits are per API key, per endpoint.

EndpointLimit
POST /analyze20/min
GET /status/<job_id>60/min
GET /credits30/min
POST /generate-video5/min
GET /video-status/<job_id>60/min
GET /videos20/min
GET/POST /characters20/min
GET /characters/<id>30/min
POST /characters/<id>/finalize10/min

When rate limited you receive HTTP 429. Wait at least 10 seconds before retrying.


Conventions

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.


Endpoints

1. Submit Ad Analysis

POST /api/v1/partner/analyze
Async 50 credits

Analyze a Facebook or Instagram ad. Submit here, then poll /status/<job_id>.

Request

{
  "url": "https://www.facebook.com/ads/library/?id=123456789"
}
FieldTypeRequiredDescription
urlstringyesFacebook/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

Response (202)

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "20260323_141500_abc123",
  "status": "queued",
  "credits_used": 50,
  "credits_remaining": 950
}

Errors

StatusError
400"Request body must be JSON"
400"Please provide a URL"
400"Please provide a valid Facebook, Instagram, or TikTok URL"
402"Insufficient credits"

Example

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"}'

2. Check Analysis Status

GET /api/v1/partner/status/<job_id>

Poll until status is complete or error.

Response — Processing (200)

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "20260323_141500_abc123",
  "status": "downloading",
  "message": "Downloading ad from Facebook..."
}

Possible status values: queued, downloading, extracting_frames, transcribing, analyzing

Response — Complete (200)

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

Errors

StatusError
400"Invalid job ID"
404"Not found" / "Job not found"

Example

curl https://knightvision.tech/api/v1/partner/status/20260323_141500_abc123 \
  -H "Authorization: Bearer kv_partner_your_key_here"

3. Check Credits

GET /api/v1/partner/credits

Response (200)

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

Example

curl https://knightvision.tech/api/v1/partner/credits \
  -H "Authorization: Bearer kv_partner_your_key_here"

4. Generate Video

POST /api/v1/partner/generate-video
Async Variable credits

Generate an AI video. Poll /video-status/<job_id> for results.

Request

{
  "prompt": "A person walking through a futuristic city",
  "model": "sora-2",
  "duration": 10,
  "aspect_ratio": "9:16"
}
FieldTypeRequiredDefaultDescription
promptstringyesVideo description, max 2000 chars
modelstringnosora-2See models below
durationintegerno10Seconds (valid values depend on model)
aspect_ratiostringno9:169:16, 16:9, or 1:1

Models & Durations

ModelValid DurationsCredits
sora-210, 1522 (10s), 25 (15s)
sora-2-pro15, 25154 (15s), 175 (25s)
kling-v3-text-to-videoany10/s (720p), 13/s (1080p)
kling-o3-text-to-videoany10/s (720p), 13/s (1080p)

Response (202)

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "sora_20260323_141500_abc123",
  "status": "queued",
  "credits_used": 22,
  "credits_remaining": 928
}

Errors

StatusError
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"

Example

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}'

5. Check Video Status

GET /api/v1/partner/video-status/<job_id>

Poll until status is complete or error.

Response — Complete (200)

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

Example

curl https://knightvision.tech/api/v1/partner/video-status/sora_20260323_141500_abc123 \
  -H "Authorization: Bearer kv_partner_your_key_here"

6. List Videos

GET /api/v1/partner/videos

List your generated videos, newest first. Optional ?limit=N (default 20, max 50).

Response (200)

{
  "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"
    }
  ]
}

Example

curl "https://knightvision.tech/api/v1/partner/videos?limit=10" \
  -H "Authorization: Bearer kv_partner_your_key_here"

7. List Characters

GET /api/v1/partner/characters

Response (200)

{
  "request_id": "a1b2c3d4e5f6",
  "characters": [
    { "id": 42, "name": "Sales Expert", "status": "ready" }
  ]
}

Example

curl https://knightvision.tech/api/v1/partner/characters \
  -H "Authorization: Bearer kv_partner_your_key_here"

8. Create Character

POST /api/v1/partner/characters
Async 22 credits

Create an AI character from a text prompt. Refunded if creation fails.

Request

{
  "name": "Sales Expert",
  "prompt": "A confident business person in a modern office",
  "duration": 10,
  "aspect_ratio": "9:16"
}
FieldTypeRequiredDefaultDescription
namestringyesMax 50 characters
promptstringyesMax 1000 characters
durationintegerno10Video duration in seconds
aspect_ratiostringno9:169:16, 16:9, or 1:1

Response (200)

Character creation is asynchronous. Poll 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
}

Example

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"}'

9. Get Character

GET /api/v1/partner/characters/<char_id>

Get details for a specific character. You can only access characters you created.

Response (200)

{
  "request_id": "a1b2c3d4e5f6",
  "character": { "id": 42, "name": "Sales Expert", "status": "ready" }
}

Example

curl https://knightvision.tech/api/v1/partner/characters/42 \
  -H "Authorization: Bearer kv_partner_your_key_here"

10. Finalize Character

POST /api/v1/partner/characters/<char_id>/finalize
3 credits

Finalize a character for use in video generation. Refunded if finalization fails.

Request (optional)

{
  "timestamp_start": 1,
  "timestamp_end": 4,
  "character_prompt": "Person looking into the camera"
}
FieldTypeDefaultDescription
timestamp_startinteger1Start timestamp for extraction
timestamp_endinteger4End timestamp for extraction
character_promptstring"Person looking into the camera"Pose description

Response (200)

{
  "request_id": "a1b2c3d4e5f6",
  "status": "finalizing",
  "credits_used": 3,
  "credits_remaining": 903
}

Example

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}'

Typical Workflows

Ad Analysis

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

Video Generation

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

Character Creation + Video

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

Webhooks

The API is currently poll-based only. Webhook support for async job completion notifications is planned for a future release.


Error Handling

All errors return a JSON object with an error field. HTTP status codes:

CodeMeaning
400Bad request (invalid input, missing fields)
401Invalid or missing API key
402Insufficient credits (includes credits_remaining)
403API key deactivated
404Resource not found or not owned by your account
429Rate limit exceeded (wait at least 10s)
500Server-side error
502Upstream provider unreachable
Status polling endpoints return HTTP 200 even when the job itself has failed. Always check the status field in the response body.

Changelog

DateChange
2026-03-27Added Kling V3 and Kling O3 models for video generation
2026-03-23Added character creation and finalization endpoints
2026-03-22Initial v1 release: ad analysis, video generation, credit management

Support

For integration help, API key requests, or bug reports, contact us at partner@knightvision.tech.