Knightvision Partner API Reference

Authorization: Bearer kv_partner_<your_api_key>

User-Agent: MyApp/1.0

{
  "url": "https://www.facebook.com/ads/library/?id=123456789"
}

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-3f9a2c1e",
  "status": "queued",
  "credits_used": 50,
  "credits_remaining": 950
}

curl -X POST https://knightvision.ai/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"}'

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-3f9a2c1e",
  "status": "downloading",
  "message": "Downloading ad from Facebook..."
}

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-3f9a2c1e",
  "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"
  }
}

curl https://knightvision.ai/api/v1/partner/status/kv-3f9a2c1e \
  -H "Authorization: Bearer kv_partner_your_key_here"

{
  "request_id": "a1b2c3d4e5f6",
  "analyses": [
    {
      "job_id": "kv-3f9a2c1e",
      "status": "complete",
      "credits_used": 50,
      "created_at": "2026-03-23 14:15:00",
      "result": { "summary": "...", "analysis": "...", "transcription": "...", "ugc_script": "..." }
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

curl "https://knightvision.ai/api/v1/partner/analyses?limit=10&offset=0" \
  -H "Authorization: Bearer kv_partner_your_key_here"

{
  "prompt": "A modern product mockup on a clean white background",
  "model": "nano-banana-pro",
  "aspect_ratio": "1:1",
  "quality": "2K",
  "quantity": 2
}

{
  "request_id": "a1b2c3d4e5f6",
  "generation_ids": [12345, 12346],
  "public_ids": ["kv-a1b2c3d4", "kv-e5f6a7b8"],
  "credits_used": 33,
  "credits_remaining": 917
}

curl -X POST https://knightvision.ai/api/v1/partner/generate-image \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A modern product mockup on a clean white background", "quantity": 2}'

curl -X POST https://knightvision.ai/api/v1/partner/generate-image \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A bold typographic poster: SALE 50% OFF, neon gradient", "model": "gpt-image-2", "quality": "4K", "aspect_ratio": "9:16"}'

{
  "request_id": "a1b2c3d4e5f6",
  "status": "success",
  "generation_id": 12345,
  "image_url": "https://knightvision.tech/static/generated_images/gen_12345.png",
  "model": "Nano Banana Pro",
  "aspect_ratio": "1:1",
  "resolution": "2K",
  "prompt": "A modern product mockup on a clean white background",
  "metadata_removed": false
}

{
  "request_id": "a1b2c3d4e5f6",
  "status": "pending",
  "generation_id": 12345
}

curl https://knightvision.ai/api/v1/partner/image-status/12345 \
  -H "Authorization: Bearer kv_partner_your_key_here"

{
  "request_id": "a1b2c3d4e5f6",
  "images": [
    {
      "generation_id": 12345,
      "public_id": "kv-a1b2c3d4",
      "partner_job_id": "lx-img-001",
      "prompt": "A modern product mockup",
      "model_used": "nano-banana-pro",
      "aspect_ratio": "1:1",
      "resolution": "2K",
      "credits_used": 17,
      "status": "success",
      "image_url": "https://knightvision.tech/static/generated_images/gen_12345.png",
      "ref_image_urls": [],
      "metadata_removed": false,
      "created_at": "2026-04-05 14:15:00"
    }
  ],
  "total": 15,
  "limit": 20,
  "offset": 0
}

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

{
  "image_url": "https://knightvision.tech/static/generated_images/kv-a1b2c3d4.png",
  "upscale_factor": 2,
  "partner_job_id": "lx-abc123"
}

{
  "request_id": "a1b2c3d4e5f6",
  "generation_id": 12345,
  "public_id": "kv-7f3a9c21",
  "job_id": "kv-2b9e4d10",
  "partner_job_id": "lx-abc123",
  "status": "pending",
  "upscale_factor": 2,
  "output": {"width": 2048, "height": 2048, "tier": "2K"},
  "credits_used": 8,
  "credits_remaining": 992
}

curl -X POST https://knightvision.ai/api/v1/partner/upscale-image \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://knightvision.tech/static/generated_images/kv-a1b2c3d4.png", "upscale_factor": 2}'

{
  "video_url": "https://knightvision.tech/static/generated_videos/kv-1a2b3c4d.mp4",
  "upscale_factor": 2,
  "partner_job_id": "lx-abc124"
}

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-5c6d7e8f",
  "partner_job_id": "lx-abc124",
  "status": "queued",
  "upscale_factor": 2,
  "input_seconds": 8,
  "output": {"width": 2560, "height": 1440},
  "credits_used": 53,
  "credits_remaining": 939
}

curl -X POST https://knightvision.ai/api/v1/partner/upscale-video \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://knightvision.tech/static/generated_videos/kv-1a2b3c4d.mp4", "upscale_factor": 2}'

{
  "image_url": "https://example.com/campaign/hero.jpg"
}

{
  "video_url": "https://example.com/campaign/spot.mp4"
}

{
  "request_id": "a1b2c3d4e5f6",
  "image_url": "https://knightvision.tech/static/clean_images/3f9c0a7d5e2b4c1f8a6d0e9b7c5a3f21.jpg",
  "format": "jpeg",
  "content_type": "image/jpeg",
  "removed": ["c2pa", "exif", "xmp"],
  "c2pa_found": true,
  "bytes_in": 2481734,
  "bytes_out": 2474302,
  "expires_at": "2026-10-05 14:15:00"
}

{
  "request_id": "a1b2c3d4e5f6",
  "video_url": "https://knightvision.tech/static/clean_videos/9b1e4c7a2d5f8e3b6a0c9d4f7e2b5a18.mp4",
  "format": "mp4",
  "content_type": "video/mp4",
  "removed": ["c2pa", "other"],
  "c2pa_found": true,
  "bytes_in": 7397371,
  "bytes_out": 7383110,
  "expires_at": "2026-10-09 14:15:00"
}

curl -X POST https://knightvision.ai/api/v1/partner/remove-metadata \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/campaign/hero.jpg"}'

curl -X POST https://knightvision.ai/api/v1/partner/remove-metadata \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://example.com/campaign/spot.mp4"}'

{
  "url": "https://www.tiktok.com/@user/video/7300000000000000000",
  "partner_job_id": "lx-abc125"
}

{
  "request_id": "a1b2c3d4e5f6",
  "download_id": "kv-7f3a9c21",
  "partner_job_id": "lx-abc125",
  "status": "pending",
  "platform": "tiktok",
  "normalized_url": "https://www.tiktok.com/@user/video/7300000000000000000",
  "retention_days": 7,
  "quota": {"limit": 200, "used": 12, "remaining": 188, "window_hours": 24, "resets_in_seconds": 51840}
}

curl -X POST https://knightvision.ai/api/v1/partner/social-download \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/7300000000000000000"}'

{
  "request_id": "a1b2c3d4e5f6",
  "download_id": "kv-7f3a9c21",
  "partner_job_id": "lx-abc125",
  "status": "complete",
  "platform": "tiktok",
  "media_kind": "video",
  "title": "How we shot this",
  "uploader": "user",
  "duration_sec": 18.7,
  "width": 1080,
  "height": 1920,
  "has_audio": true,
  "bytes": 4271104,
  "file_count": 1,
  "retention_days": 7,
  "files": [
    {
      "idx": 0,
      "kind": "video",
      "download_name": "tiktok_7300000000000000000.mp4",
      "bytes": 4270976,
      "duration_sec": 18.7,
      "width": 1080,
      "height": 1920,
      "has_audio": true,
      "available": true,
      "stream_url": "/api/v1/partner/social-download/kv-7f3a9c21/file/0",
      "download_url": "/api/v1/partner/social-download/kv-7f3a9c21/file/0?download=1"
    },
    {
      "idx": 1,
      "kind": "cover",
      "for_idx": 0,
      "download_name": "tiktok_7300000000000000000_cover.jpg",
      "available": true,
      "stream_url": "/api/v1/partner/social-download/kv-7f3a9c21/file/1",
      "download_url": "/api/v1/partner/social-download/kv-7f3a9c21/file/1?download=1"
    }
  ],
  "error": null
}

curl -L https://knightvision.ai/api/v1/partner/social-download/kv-7f3a9c21/file/0?download=1 \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -o clip.mp4

{
  "request_id": "a1b2c3d4e5f6",
  "downloads": [{"download_id": "kv-7f3a9c21", "status": "complete", "platform": "tiktok", "files": []}]
}

{
  "prompt": "A person walking through a futuristic city",
  "model": "kling-v3-text-to-video",
  "duration": 10,
  "aspect_ratio": "9:16",
  "quality": "1080p",
  "sound": true
}

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-7b2d9e10",
  "partner_job_id": null,
  "status": "queued",
  "credits_used": 220,
  "credits_remaining": 730
}

curl -X POST https://knightvision.ai/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": "kling-v3-text-to-video", "duration": 10, "quality": "1080p"}'

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-7b2d9e10",
  "status": "processing",
  "progress": 40,
  "message": "Generating video..."
}

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-7b2d9e10",
  "status": "complete",
  "video_url": "https://knightvision.tech/static/generated_videos/kv-7b2d9e10.mp4",
  "duration": 10,
  "metadata_removed": false
}

curl https://knightvision.ai/api/v1/partner/video-status/kv-7b2d9e10 \
  -H "Authorization: Bearer kv_partner_your_key_here"

{
  "request_id": "a1b2c3d4e5f6",
  "videos": [
    {
      "job_id": "kv-7b2d9e10",
      "partner_job_id": "lx-vid-001",
      "prompt": "A person walking through a futuristic city",
      "model": "kling-v3-text-to-video",
      "model_used": "kling-v3-text-to-video",
      "duration": 10,
      "aspect_ratio": "9:16",
      "credits_used": 110,
      "status": "complete",
      "video_url": "https://knightvision.tech/static/generated_videos/kv-7b2d9e10.mp4",
      "start_frame_url": null,
      "end_frame_url": null,
      "created_at": "2026-04-05 14:15:00",
      "metadata_removed": false
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

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

{
  "request_id": "a1b2c3d4e5f6",
  "fonts": [
    {"key": "inter", "label": "Inter", "file": "Inter-Bold.ttf", "css_family": "Inter", "embolden": 0, "category": "clean"},
    {"key": "montserrat", "label": "Montserrat", "file": "Montserrat-ExtraBold.ttf", "css_family": "Montserrat ExtraBold", "embolden": 0, "category": "clean"},
    {"key": "arimo", "label": "Arimo", "file": "Arimo-Regular.ttf", "css_family": "Arimo", "embolden": 0.036, "category": "clean"},
    {"key": "pacifico", "label": "Pacifico", "file": "Pacifico-Regular.ttf", "css_family": "Pacifico", "embolden": 0, "category": "handwritten"}
  ],
  "presets": [
    {"key": "tiktok", "label": "TikTok", "style": {"font": "arimo", "size": "medium", "color": "#FFFFFF",
      "outline_color": "#000000", "outline": "none", "shadow": "thin", "shadow_blur": 4, "shadow_x": 2,
      "shadow_y": 2.5, "shadow_strength": 70, "position": "bottom", "position_y": 50, "chunking": "phrases",
      "case": "normal"}}
  ],
  "chunking": ["words", "phrases", "line"],
  "cases": ["normal", "lower", "upper"],
  "sizes": ["small", "medium", "large"],
  "outlines": ["none", "thin", "medium", "thick"],
  "shadows": ["none", "thin", "medium", "thick"],
  "positions": ["bottom", "middle", "top", "custom"],
  "position_y": {"min": 5, "max": 95, "default": 50},
  "shadow_blur": {"min": 0, "max": 20, "default": 0, "step": 1},
  "shadow_x": {"min": -20, "max": 20, "default": null, "step": 1},
  "shadow_y": {"min": -20, "max": 20, "default": null, "step": 1},
  "shadow_strength": {"min": 0, "max": 100, "default": 100, "step": 1},
  "default": {
    "font": "inter", "size": "medium", "color": "#FFFFFF",
    "outline_color": "#000000", "outline": "medium", "shadow": "none",
    "shadow_blur": 0, "shadow_x": null, "shadow_y": null,
    "shadow_strength": 100, "position": "bottom", "position_y": 50,
    "chunking": "words", "case": "normal"
  },
  "credits": 25,
  "upload": {
    "chunked": true,
    "chunk_size": 8388608,
    "max_bytes": 1000000000,
    "max_seconds": 1800,
    "single_shot_max_bytes": 95000000
  },
  "retention": {
    "captioned_output_days": 14,
    "uploaded_source_days": 2,
    "guaranteed": false
  }
}

curl https://knightvision.ai/api/v1/partner/captions/style-options \
  -H "Authorization: Bearer kv_partner_your_key_here"

{
  "video_job_id": "kv-1a2b3c4d",
  "partner_job_id": "campaign-42-captions",
  "style": {
    "font": "anton",
    "size": "large",
    "color": "#FFFFFF",
    "outline_color": "#000000",
    "outline": "thick",
    "shadow": "medium",
    "position": "bottom"
  }
}

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-a1b2c3d4",
  "partner_job_id": "campaign-42-captions",
  "status": "pending",
  "credits_used": 25,
  "credits_remaining": 975
}

curl -X POST https://knightvision.ai/api/v1/partner/captions \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"video_job_id":"kv-1a2b3c4d","partner_job_id":"campaign-42-captions","style":{"font":"anton","size":"large"}}'

curl -X POST https://knightvision.ai/api/v1/partner/captions/upload \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -F "video=@./source.mp4;type=video/mp4" \
  -F 'style={"font":"montserrat","position":"bottom"}' \
  -F "partner_job_id=campaign-42-upload"

{
  "filename": "source.mp4",
  "size_bytes": 240000000,
  "partner_job_id": "campaign-42-large",
  "style": {"font": "anton", "size": "large"}
}

{
  "request_id": "a1b2c3d4e5f6",
  "session_id": "kv-e5f6a7b8",
  "partner_job_id": "campaign-42-large",
  "chunk_size": 8388608,
  "part_count": 29,
  "max_bytes": 1000000000,
  "max_seconds": 1800,
  "credits": 25,
  "retention": {
    "captioned_output_days": 14,
    "uploaded_source_days": 2,
    "guaranteed": false
  }
}

curl -X POST https://knightvision.ai/api/v1/partner/captions/uploads/init \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"filename":"source.mp4","size_bytes":240000000,"partner_job_id":"campaign-42-large"}'

{
  "request_id": "a1b2c3d4e5f6",
  "index": 0,
  "received_parts": 1,
  "received_bytes": 8388608,
  "total_bytes": 240000000
}

curl -X POST https://knightvision.ai/api/v1/partner/captions/uploads/kv-e5f6a7b8/part/0 \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./part-0000.bin

{
  "style": {"font": "anton", "size": "large", "position": "bottom"}
}

curl -X POST https://knightvision.ai/api/v1/partner/captions/uploads/kv-e5f6a7b8/finalize \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"style":{"font":"anton","size":"large"}}'

{"request_id": "a1b2c3d4e5f6", "ok": true, "session_id": "kv-e5f6a7b8"}

curl -X POST https://knightvision.ai/api/v1/partner/captions/uploads/kv-e5f6a7b8/abort \
  -H "Authorization: Bearer kv_partner_your_key_here"

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-a1b2c3d4",
  "partner_job_id": "campaign-42-captions",
  "status": "complete",
  "captioned_url": "https://knightvision.tech/static/captioned_videos/kv-a1b2c3d4.mp4",
  "media_pruned": false,
  "credits_used": 25,
  "credits_refunded": false,
  "edit_count": 0,
  "editable": true,
  "source_available": true,
  "retention": {
    "captioned_output_days": 14,
    "uploaded_source_days": null,
    "guaranteed": false
  },
  "error": null,
  "created_at": "2026-08-15 12:00:00",
  "completed_at": "2026-08-15 12:00:14"
}

curl https://knightvision.ai/api/v1/partner/captions/kv-a1b2c3d4 \
  -H "Authorization: Bearer kv_partner_your_key_here"

{
  "request_id": "a1b2c3d4e5f6",
  "captions": [
    {
      "job_id": "kv-a1b2c3d4",
      "partner_job_id": "campaign-42-captions",
      "status": "complete",
      "captioned_url": "https://knightvision.tech/static/captioned_videos/kv-a1b2c3d4.mp4",
      "media_pruned": false,
      "credits_used": 25,
      "credits_refunded": false,
      "edit_count": 0,
      "editable": true,
      "source_available": true,
      "retention": {
        "captioned_output_days": 14,
        "uploaded_source_days": null,
        "guaranteed": false
      },
      "error": null,
      "created_at": "2026-08-15 12:00:00",
      "completed_at": "2026-08-15 12:00:14"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

curl "https://knightvision.ai/api/v1/partner/captions?limit=20&offset=0" \
  -H "Authorization: Bearer kv_partner_your_key_here"

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-a1b2c3d4",
  "partner_job_id": "campaign-42-captions",
  "status": "complete",
  "chunks": [
    {"start": 0.42, "end": 1.31, "text": "Create better ads"},
    {"start": 1.32, "end": 2.15, "text": "in less time"}
  ],
  "chunk_count": 2,
  "too_many_to_edit": false,
  "max_inline_edit_chunks": 800,
  "editable": true,
  "source_available": true
}

curl https://knightvision.ai/api/v1/partner/captions/kv-a1b2c3d4/chunks \
  -H "Authorization: Bearer kv_partner_your_key_here"

{
  "chunks": [
    {"start": 0.42, "end": 1.31, "text": "Create stronger ads"},
    {"start": 1.32, "end": 2.15, "text": "in less time"}
  ]
}

curl -X POST https://knightvision.ai/api/v1/partner/captions/kv-a1b2c3d4/edit \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"chunks":[{"start":0.42,"end":1.31,"text":"Create stronger ads"}]}'

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-5d4c3b2a",
  "partner_job_id": "lx-anim-1",
  "status": "queued",
  "credits_used": 172,
  "credits_remaining": 828
}

curl -X POST https://knightvision.ai/api/v1/partner/generate-animation \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "smooth morph between the two product shots",
    "start_image_url": "https://example.com/frame1.jpg",
    "end_image_url": "https://example.com/frame2.jpg",
    "aspect_ratio": "9:16"
  }'

{
  "request_id": "a1b2c3d4e5f6",
  "merge_id": "kv-6e5f4a3b",
  "partner_job_id": null,
  "merged_url": "https://knightvision.tech/static/merged_videos/kv-6e5f4a3b.mp4",
  "credits_used": 110,
  "credits_remaining": 718
}

curl -X POST https://knightvision.ai/api/v1/partner/merge-videos \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"job_ids": ["kv-5d4c3b2a", "kv-7b2d9e10"]}'

{
  "request_id": "a1b2c3d4e5f6",
  "character_id": "kv-2a3b4c5d",
  "partner_job_id": null,
  "name": "Spokesperson",
  "description": "friendly presenter in a navy blazer",
  "image_url": "https://knightvision.tech/static/omni_characters/kv-2a3b4c5d.jpg",
  "voice_id": null,
  "credits_used": 33,
  "credits_remaining": 967
}

{
  "request_id": "a1b2c3d4e5f6",
  "characters": [
    {
      "character_id": "kv-2a3b4c5d",
      "partner_job_id": null,
      "name": "Spokesperson",
      "description": "friendly presenter in a navy blazer",
      "image_url": "https://knightvision.tech/static/omni_characters/kv-2a3b4c5d.jpg",
      "voice": {"id": "kv-3c4d5e6f", "name": "Warm narrator", "base_voice": "sulafat", "base_voice_name": "Sulafat"},
      "created_at": "2026-06-26 10:00:00"
    }
  ]
}

{
  "request_id": "a1b2c3d4e5f6",
  "presets": [
    {"id": "kore", "name": "Kore", "gender": "female", "traits": "Firm, mid pitch", "sample_url": "https://knightvision.tech/static/omni_voice_samples/kore.mp3"},
    {"id": "puck", "name": "Puck", "gender": "male", "traits": "Upbeat, mid pitch", "sample_url": "https://knightvision.tech/static/omni_voice_samples/puck.mp3"}
  ]
}

{
  "request_id": "a1b2c3d4e5f6",
  "voice_id": "kv-3c4d5e6f",
  "partner_job_id": null,
  "name": "Warm narrator",
  "base_voice": "sulafat",
  "base_voice_name": "Sulafat",
  "gender": "female",
  "traits": "Warm, mid pitch",
  "description": "calm, friendly, unhurried",
  "example_dialogue": "Let me show you how it works.",
  "sample_url": "https://knightvision.tech/static/omni_voice_samples/sulafat.mp3",
  "created_at": "2026-09-25 10:00:00"
}

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-9f8e7d6c",
  "partner_job_id": null,
  "status": "processing",
  "model": "omni",
  "duration": 8,
  "aspect_ratio": "9:16",
  "resolution": "1080p",
  "credits_used": 154,
  "credits_remaining": 846
}

curl -X POST https://knightvision.ai/api/v1/partner/omni/video \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "the spokesperson presents the product on a bright set",
    "character_ids": ["kv-2a3b4c5d"],
    "voice_ids": ["kv-3c4d5e6f"],
    "duration": 8,
    "resolution": "1080p"
  }'

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-9f8e7d6c",
  "status": "complete",
  "model": "omni",
  "prompt": "the spokesperson presents the product on a bright set",
  "character_ids": ["kv-2a3b4c5d"],
  "voice_ids": ["kv-3c4d5e6f"],
  "first_frame_url": null,
  "last_frame_url": null,
  "duration": 8,
  "aspect_ratio": "9:16",
  "resolution": "1080p",
  "video_url": "https://knightvision.tech/static/omni_videos/kv-9f8e7d6c/video.mp4",
  "error": null,
  "prompt_fixable": false,
  "credits_used": 154,
  "credits_refunded": 0,
  "created_at": "2026-06-26 10:05:00",
  "metadata_removed": false
}

{
  "request_id": "a1b2c3d4e5f6",
  "batch_id": "kv-4b3a2c1d",
  "partner_job_id": null,
  "status": "processing",
  "aspect_ratio": "9:16",
  "resolution": "1080p",
  "section_count": 2,
  "jobs": [
    {"section_id": "hook", "title": "HOOK", "job_id": "kv-1c2d3e4f", "duration": 8, "credits_used": 154},
    {"section_id": "body", "title": "BODY", "job_id": "kv-5a6b7c8d", "duration": 10, "credits_used": 154}
  ],
  "credits_used": 308,
  "credits_remaining": 692
}

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-0d1e2f3a",
  "source_job_id": "kv-9f8e7d6c",
  "improved_prompt": "a person dancing on a bright set",
  "credits_used": 2,
  "credits_remaining": 998
}

{
  "name": "My Run",
  "character_image_url": "https://example.com/character.jpg",
  "use_as_character_reference": true,
  "prompt": "=== SCENE: Living Room ===\nModern apartment, afternoon light, sofa.\n\n=== SCENE: Kitchen ===\nBright kitchen, character holding a coffee mug.\n\n=== DIALOGUE 1 ===\nI used to dread mornings...\n\n=== DIALOGUE 2 ===\nMy friends keep asking me what I changed.\n"
}

=== SCENE: Kitchen ===
CHARACTER: Anna          <-- metadata, stripped from the prompt
Bright kitchen, morning light.

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-8e7d6c5b",
  "partner_job_id": null,
  "status": "processing",
  "scene_count": 2,
  "credits_used": 121,
  "credits_remaining": 4079,
  "model": "veo-3.1-fast",
  "image_model": "nano-banana-pro",
  "cost_per_scene": 55
}

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-8e7d6c5b",
  "name": "My Run",
  "status": "complete",
  "scene_count": 2,
  "scenes_complete": 2,
  "scenes": [
    {
      "name": "Living Room",
      "status": "complete",
      "setting": "Modern apartment, afternoon light, sofa.",
      "dialogue": "I used to dread mornings...",
      "start_image_url": "https://knightvision.tech/static/generated_images/srwk_12345.png",
      "video_url": "https://knightvision.tech/static/generated_videos/kv-1f2e3d4c.mp4"
    },
    {
      "name": "Kitchen",
      "status": "complete",
      "setting": "Bright kitchen, character holding a coffee mug.",
      "dialogue": "My friends keep asking me what I changed.",
      "start_image_url": "https://knightvision.tech/static/generated_images/srwk_67890.png",
      "video_url": "https://knightvision.tech/static/generated_videos/kv-5b6a7f8e.mp4"
    }
  ],
  "credits_charged": 121,
  "credits_refunded": 0,
  "model": "veo-3.1-fast",
  "image_model": "nano-banana-pro",
  "cost_per_scene": 55,
  "error": null,
  "created_at": "2026-04-20 08:12:03",
  "updated_at": "2026-04-20 08:18:51"
}

{
  "request_id": "a1b2c3d4e5f6",
  "total": 12,
  "limit": 20,
  "offset": 0,
  "runs": [
    {"job_id": "kv-8e7d6c5b", "partner_job_id": null, "name": "My Run", "model_used": "veo-3.1-fast", "image_model_used": "nano-banana-pro", "status": "complete", "scene_count": 2, "credits_charged": 121, "credits_refunded": 0, "created_at": "2026-04-20 08:12:03", "updated_at": "2026-04-20 08:18:51"}
  ]
}

{
  "request_id": "a1b2c3d4e5f6",
  "voices": [
    {
      "voice_id": "EXAVITQu4vr4xnSDxMaL",
      "name": "Bella",
      "lang": "EN",
      "gender": "female",
      "description": "Warm, professional — brand narration"
    }
  ],
  "models": [
    {"id": "eleven_v4_turbo", "label": "v4 Turbo"},
    {"id": "eleven_v4", "label": "v4"},
    {"id": "eleven_turbo_v2_5", "label": "Turbo v2.5"},
    {"id": "eleven_v3", "label": "v3"}
  ],
  "default_model": "eleven_v4_turbo"
}

curl https://knightvision.ai/api/v1/partner/voiceover/voices \
  -H "Authorization: Bearer kv_partner_your_key_here"

{
  "text": "Tired of bloated SaaS? Try the lean alternative.",
  "voice_id": "EXAVITQu4vr4xnSDxMaL",
  "model_id": "eleven_v4_turbo",
  "output_format": "mp3_44100_128"
}

{
  "request_id": "a1b2c3d4e5f6",
  "id": 42,
  "job_id": "kv-9c8b7a65",
  "audio_url": "https://knightvision.tech/static/generated_voiceovers/vo_42_a1b2c3d4.mp3",
  "voice_id": "EXAVITQu4vr4xnSDxMaL",
  "voice_name": "Bella",
  "model_id": "eleven_v4_turbo",
  "char_count": 47,
  "credits_used": 2,
  "credits_remaining": 998
}

curl -X POST https://knightvision.ai/api/v1/partner/generate-voiceover \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world.", "voice_id": "EXAVITQu4vr4xnSDxMaL", "model_id": "eleven_v4_turbo"}'

{
  "request_id": "a1b2c3d4e5f6",
  "voiceovers": [
    {
      "id": 42,
      "job_id": "kv-9c8b7a65",
      "text": "Hello world.",
      "voice_id": "EXAVITQu4vr4xnSDxMaL",
      "voice_name": "Bella",
      "model_id": "eleven_v4_turbo",
      "char_count": 12,
      "credits_used": 2,
      "audio_url": "https://knightvision.tech/static/generated_voiceovers/vo_42_a1b2c3d4.mp3",
      "status": "success",
      "error_message": null,
      "source": "",
      "created_at": "2026-05-09 12:00:00"
    }
  ],
  "total": 1,
  "limit": 30,
  "offset": 0
}

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

{
  "prompt": "an upbeat synthwave track with driving drums and a hopeful mood",
  "model": "V5_5",
  "instrumental": false,
  "style": "Synthwave",
  "title": "Midnight Drive"
}

{
  "request_id": "a1b2c3d4e5f6",
  "id": 42,
  "job_id": "kv-c4d5e6f7",
  "partner_job_id": null,
  "status": "queued",
  "model": "V5_5",
  "credits_used": 11,
  "credits_remaining": 989
}

curl -X POST https://knightvision.ai/api/v1/partner/generate-music \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a calm lo-fi beat to study to", "model": "V5_5"}'

{
  "source": {
    "kind": "kv_music",
    "ref": "kv-a1b2c3d4",
    "track": 0
  },
  "continue_at": 42.5,
  "mode": "original",
  "prompt": "continue with a restrained guitar solo",
  "partner_job_id": "catalog-track-184"
}

curl -X POST https://knightvision.ai/api/v1/partner/extend-music \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Idempotency-Key: music_extend_184_take_1" \
  -H "Content-Type: application/json" \
  -d '{"source":{"kind":"kv_music","ref":"kv-a1b2c3d4","track":0},"continue_at":42.5,"mode":"original","prompt":"continue with a restrained guitar solo","partner_job_id":"catalog-track-184"}'

curl -X POST https://knightvision.ai/api/v1/partner/extend-music \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Idempotency-Key: upload_extend_20260816_001" \
  -F "audio=@./source-track.wav" \
  -F 'parameters={"continue_at":38.0,"mode":"custom","model":"V5_5","prompt":"instrumental bridge, then return to the main theme","style":"cinematic electronic","title":"Extended Theme","instrumental":true,"partner_job_id":"upload-extend-001"}'

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-e5f6a7b8",
  "partner_job_id": "catalog-track-184",
  "status": "queued",
  "operation": "extend",
  "model": "V5_5",
  "credits_used": 11,
  "credits_remaining": 989,
  "idempotency_key": "music_extend_184_take_1"
}

{
  "request_id": "f6e5d4c3b2a1",
  "job_id": "kv-e5f6a7b8",
  "partner_job_id": "catalog-track-184",
  "status": "queued",
  "operation": "extend",
  "model": "V5_5",
  "credits_used": 11,
  "credits_remaining": 989,
  "idempotency_key": "music_extend_184_take_1",
  "deduplicated": true
}

{
  "request_id": "a1b2c3d4e5f6",
  "job_id": "kv-e5f6a7b8",
  "partner_job_id": "catalog-track-184",
  "status": "complete",
  "operation": "extend",
  "model": "V5_5",
  "credits_used": 11,
  "tracks": [
    {
      "audio_url": "https://knightvision.tech/static/generated_music/kv-e5f6a7b8_0.mp3",
      "image_url": "https://knightvision.tech/static/generated_music/kv-e5f6a7b8_0.jpg",
      "title": "Extended Theme",
      "duration": 201.1
    }
  ]
}

curl "https://knightvision.ai/api/v1/partner/music-status/kv-e5f6a7b8" \
  -H "Authorization: Bearer kv_partner_your_key_here"

{
  "request_id": "a1b2c3d4e5f6",
  "music": [
    {
      "job_id": "kv-e5f6a7b8",
      "partner_job_id": "catalog-track-184",
      "status": "complete",
      "operation": "extend",
      "model": "V5_5",
      "title": "Extended Theme",
      "credits_used": 11,
      "tracks": [
        {
          "audio_url": "https://knightvision.tech/static/generated_music/kv-e5f6a7b8_0.mp3",
          "image_url": "https://knightvision.tech/static/generated_music/kv-e5f6a7b8_0.jpg",
          "title": "Extended Theme",
          "duration": 201.1
        }
      ],
      "created_at": "2026-08-16 12:00:00",
      "completed_at": "2026-08-16 12:03:00"
    }
  ],
  "total": 1,
  "limit": 30,
  "offset": 0
}

curl "https://knightvision.ai/api/v1/partner/music?limit=30&offset=0" \
  -H "Authorization: Bearer kv_partner_your_key_here"

{
  "request_id": "a1b2c3d4e5f6",
  "credits_remaining": 950,
  "pricing_tier": "api_plus10",
  "credit_cost_per_analysis": 50,
  "costs": {
    "analysis": 50,
    "text_analysis": 5,
    "captions": 25,
    "image_per_image": 15,
    "image_per_image_2k": 15,
    "image_per_image_4k": 22,
    "image_models": {
      "nano-banana-pro": {
        "2K": 15,
        "4K": 22
      },
      "gpt-image-2": {
        "1K": 19,
        "2K": 24,
        "4K": 29
      },
      "gpt-image-2-5-flare": {
        "1K": 22,
        "2K": 28,
        "4K": 34
      },
      "gpt-image-2-5-sunburst": {
        "1K": 22,
        "2K": 28,
        "4K": 34
      }
    },
    "video": {
      "kling-v3-text-to-video": {
        "per_clip": true,
        "combos": {
          "720p_5s_noaudio": 50,
          "720p_10s_noaudio": 100,
          "1080p_5s_noaudio": 65,
          "1080p_10s_noaudio": 150,
          "720p_5s_audio": 75,
          "720p_10s_audio": 145,
          "1080p_5s_audio": 100,
          "1080p_10s_audio": 200
        }
      },
      "kling-v3-image-to-video": {
        "per_clip": true,
        "combos": {
          "720p_5s_noaudio": 50,
          "720p_10s_noaudio": 100,
          "1080p_5s_noaudio": 65,
          "1080p_10s_noaudio": 150,
          "720p_5s_audio": 75,
          "720p_10s_audio": 145,
          "1080p_5s_audio": 100,
          "1080p_10s_audio": 200
        }
      },
      "kling-v3-motion-control": {
        "per_second": true,
        "720p": 14,
        "1080p": 19
      },
      "seedance-2-direct": {
        "per_second": true,
        "480p": 14,
        "720p": 29,
        "1080p": 72,
        "4K": 146,
        "with_reference_video": {
          "basis": "reference_plus_output_seconds",
          "480p": 9,
          "720p": 18,
          "1080p": 44,
          "4K": 90
        }
      },
      "seedance-2-5": {
        "per_second": true,
        "480p": 20,
        "720p": 45,
        "1080p": 111,
        "with_reference_video": {
          "basis": "reference_plus_output_seconds",
          "480p": 12,
          "720p": 27,
          "1080p": 67
        }
      },
      "veo-3.1-quality": {
        "per_second": false,
        "flat": {
          "720p": 150,
          "1080p": 178,
          "4K": 200
        }
      },
      "veo-3.1-fast": {
        "per_second": false,
        "flat": {
          "720p": 41,
          "1080p": 49,
          "4K": 120
        }
      }
    },
    "animation": 156,
    "merge_videos": 100,
    "omni": {
      "character_creation": 30,
      "voice_creation": 0,
      "video_price": {
        "1080p": {
          "4": 120,
          "6": 130,
          "8": 140,
          "10": 150
        },
        "4k": {
          "4": 180,
          "6": 190,
          "8": 200,
          "10": 210
        }
      },
      "models": [
        "omni",
        "omni-1.1"
      ]
    },
    "voiceover": {
      "models": {
        "eleven_v4_turbo": {
          "chars_per_credit": 80,
          "label": "v4 Turbo"
        },
        "eleven_v4": {
          "chars_per_credit": 40,
          "label": "v4"
        },
        "eleven_turbo_v2_5": {
          "chars_per_credit": 80,
          "label": "Turbo v2.5"
        },
        "eleven_v3": {
          "chars_per_credit": 50,
          "label": "v3"
        }
      },
      "default_model": "eleven_v4_turbo",
      "min_credits": 1,
      "max_text_length": 5000
    },
    "music": {
      "models": {
        "V5_5": 10,
        "V5": 10
      },
      "default_model": "V5_5",
      "flat_per_generation": 10,
      "tracks_per_generation": 2
    },
    "upscale": {
      "image": {
        "per_image_by_output_tier": {
          "2K": 7,
          "4K": 14,
          "8K": 28
        },
        "tier_max_long_edge": {
          "2K": 2048,
          "4K": 4096,
          "8K": 8192
        },
        "factors": [
          1,
          2,
          4
        ],
        "input_max_bytes": 10000000,
        "max_output_long_edge": 8192
      },
      "video": {
        "per_second_by_factor": {
          "1": 6,
          "2": 6,
          "4": 10
        },
        "basis": "ceil(input_seconds)",
        "factors": [
          1,
          2,
          4
        ],
        "input_max_bytes": 50000000,
        "input_max_seconds": 120,
        "max_output_long_edge": 4096
      }
    }
  }
}

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

{
  "request_id": "a1b2c3d4e5f6",
  "name": "Acme Corp",
  "api_key_prefix": "kv_partner_abc12345",
  "pricing_tier": "api_plus10",
  "credits_remaining": 4200,
  "is_active": true,
  "created_at": "2026-02-01 10:00:00",
  "last_active": "2026-04-20 09:15:33"
}

{
  "request_id": "a1b2c3d4e5f6",
  "since": "2026-04-01T00:00:00",
  "credits_remaining": 4200,
  "total_calls": 312,
  "total_credits_used": 5840,
  "per_endpoint": [
    {"endpoint": "/api/v1/partner/generate-video", "calls": 42, "credits_used": 4200},
    {"endpoint": "/api/v1/partner/analyze", "calls": 28, "credits_used": 1400}
  ]
}

{
  "request_id": "a1b2c3d4e5f6",
  "total": 178,
  "limit": 50,
  "offset": 0,
  "transactions": [
    {"amount": -121, "type": "usage", "description": "Script Runner (2 scenes): My Run", "created_at": "2026-04-20 08:12:03"},
    {"amount": 55, "type": "refund", "description": "Refund: Script Runner scene failures (kv-8e7d6c5b)", "created_at": "2026-04-20 08:18:51"}
  ]
}

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-image                → get generation_id(s)
2. GET  /api/v1/partner/image-status/<generation_id>  → poll every 3-5s until "success" or "failed"
3. Download image from image_url

1. POST /api/v1/partner/generate-image    → create reference image of your character
2. Wait for image_url
3. POST /api/v1/partner/generate-video    → pass image_url + image-to-video model
4. GET  /api/v1/partner/video-status/<job_id> → poll until "complete"
5. Download video from video_url

1. Complete a Partner API video job
2. POST /api/v1/partner/captions                 → pass its video_job_id; get Caption job_id
3. GET  /api/v1/partner/captions/<job_id>        → poll until complete, no_speech, or failed
4. Download captioned_url promptly (normal 14-day window; storage pressure may prune sooner)
5. Optional: GET /captions/<job_id>/chunks, correct text, POST /captions/<job_id>/edit, then poll again

1. POST /api/v1/partner/captions/uploads/init     → get session_id, chunk_size, part_count
2. POST each raw part to /captions/uploads/<session_id>/part/<index>
3. POST /captions/uploads/<session_id>/finalize  → the only credit deduction; get Caption job_id
4. GET  /api/v1/partner/captions/<job_id>        → poll to a terminal status

1. POST /api/v1/partner/script-runner            → submit script + character_image_url
2. GET  /api/v1/partner/script-runner/<job_id>   → poll every 5-10s until "complete" or "partial"
3. Iterate scenes[].video_url for the rendered clips

1. Choose a completed partner-owned music job, or an audio file up to 95,000,000 bytes / 8 minutes
2. POST /api/v1/partner/extend-music with a unique Idempotency-Key header → get job_id
3. GET  /api/v1/partner/music-status/<job_id>                        → poll until "complete" or "error"
4. Download the returned tracks
5. If the submit response was lost, GET /api/v1/partner/music and match partner_job_id

1. (optional) GET /api/v1/partner/voiceover/voices  → list voice_ids + models
2. POST /api/v1/partner/generate-voiceover          → returns audio_url synchronously
3. Download or hotlink audio_url

POST https://example.com/knightvision/webhook
Content-Type: application/json
User-Agent: Knightvision-Webhooks/1.0
X-Knightvision-Event: video.completed
X-Knightvision-Event-Id: evt_3f9c2a7b1d0e4c55
X-Knightvision-Delivery-Attempt: 1
X-Knightvision-Signature: t=1760380800,v1=5d41402abc4b2a76b9719d911017c592e3a1f0c9b8d7e6f5a4b3c2d1e0f9a8b7

{
  "id": "evt_3f9c2a7b1d0e4c55",
  "event": "video.completed",
  "created_at": 1760380800,
  "data": {
    "job_id": "kv-7b2d9e10",
    "partner_job_id": "order-42-clip-07",
    "status": "complete",
    "model": "kling-v3-image-to-video",
    "duration": 5,
    "aspect_ratio": "9:16",
    "credits_used": 77,
    "credits_refunded": 0,
    "video_url": "https://knightvision.ai/static/generated_videos/kv-7b2d9e10.mp4",
    "error": null,
    "created_at": "2026-10-13 18:00:00"
  }
}

# Python
import hmac, hashlib, time

def verify(secret: str, header: str, raw_body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, v1 = int(parts["t"]), parts["v1"]
    if abs(time.time() - t) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

// Node.js
const crypto = require("crypto");

function verify(secret, header, rawBody) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.`).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

{
  "request_id": "a1b2c3d4e5f6",
  "url": "https://example.com/knightvision/webhook",
  "secret": "whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0f9e8d7c6b5a49382",
  "events": ["video.completed", "video.failed", "omni_video.completed", "omni_video.failed", "webhook.test"],
  "max_attempts": 6,
  "retry_delays_seconds": [60, 300, 1800, 7200, 21600],
  "signature_header": "X-Knightvision-Signature"
}

curl -X POST "https://knightvision.ai/api/v1/partner/webhook" \
  -H "Authorization: Bearer kv_partner_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/knightvision/webhook"}'

{
  "request_id": "a1b2c3d4e5f6",
  "delivered": true,
  "status_code": 200,
  "error": null,
  "event_id": "evt_3f9c2a7b1d0e4c55",
  "url": "https://example.com/knightvision/webhook"
}

{
  "request_id": "a1b2c3d4e5f6",
  "deliveries": [
    {
      "event_id": "evt_3f9c2a7b1d0e4c55",
      "event": "video.completed",
      "job_id": "kv-7b2d9e10",
      "url": "https://example.com/knightvision/webhook",
      "status": "delivered",
      "attempt": 1,
      "max_attempts": 6,
      "last_status_code": 200,
      "last_error": null,
      "created_at": 1760380800,
      "last_attempt_at": 1760380801,
      "next_attempt_at": null,
      "delivered_at": 1760380801
    }
  ],
  "limit": 50
}