API documentation

Quickstart

1. 1

   Get a key

   Open the developer dashboard and submit a request. A key is issued immediately — but in "pending" status.

2. 2

   Wait for activation

   We'll contact you for activation and payment. Then status becomes "active".

3. 3

   Make your first call

   Pass the key as Authorization: Bearer header and POST to /v1/identify.

curl -X POST https://bdkino.com/api/v1/identify \
  -H "Authorization: Bearer bdk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "robot collects garbage on an abandoned Earth",
    "lang": "en"
  }'

Authentication

Every request must contain an Authorization header with an active key. Without it — 401.

Authorization: Bearer bdk_live_xxxxxxxxxxxx

Endpoint: identify a movie

Accepts an image (base64) and/or text description. Returns matches from the bdkino database sorted by confidence.

Request parameters

* At least one — image_base64 OR description must be provided (both allowed).

Example: search by description

curl -X POST https://bdkino.com/api/v1/identify \
  -H "Authorization: Bearer bdk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "robot collects garbage on an abandoned Earth",
    "lang": "en"
  }'

Example: search by frame

# Encode JPEG/PNG/WebP as base64 and put it in place of <BASE64>
curl -X POST https://bdkino.com/api/v1/identify \
  -H "Authorization: Bearer bdk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "image_base64": "<BASE64>",
    "lang": "en"
  }'

Response format

{
  "found": true,
  "source": "text",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "results": [
    {
      "id": 10681,
      "media_type": "movie",
      "title": "WALL·E",
      "year": 2008,
      "overview": "In the distant future, a small waste-collecting robot...",
      "poster_url": "https://bdkino.com/api/img/w500/hbhFnRzhIxs...",
      "blur_b64": "data:image/webp;base64,UklGRk...",
      "vote_average": 8.0,
      "vote_count": 19234,
      "popularity": 87.5,
      "confidence": 0.91,
      "genres":             ["Animation", "Family", "Sci-Fi"],
      "keywords":           ["robot", "earth", "garbage", "love"],
      "cast":               ["Ben Burtt", "Elissa Knight", "Jeff Garlin"],
      "directors":          ["Andrew Stanton"],
      "origin_country":     ["US"],
      "original_language":  "en",
      "tagline":            "An adventure beyond the ordinary world.",
      "runtime":            98,
      "age_rating":         "G",
      "collection_id":      null,
      "collection_name":    null
    }
  ],
  "fallback_url": "https://bdkino.com/search"
}

Field reference

Feedback: help train the AI

Each /v1/identify call returns a request_id in the response. Send it back with a vote (correct / wrong) — this goes into the Cinemind training set. A free feedback loop that improves accuracy for everyone.

Request parameters

Example

curl -X POST https://bdkino.com/api/v1/identify/feedback \
  -H "Authorization: Bearer bdk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "vote": "yes",
    "id": 603,
    "media_type": "movie"
  }'

Response

{
  "ok": true,
  "vote": "yes",
  "training_pair_added": true,
  "message": "Thanks! Your vote helps train the AI."
}

Error codes

All errors return JSON of the form {"detail":"<error_code>"}.

Limits & behavior

On 429, wait until the next hour and retry; client-side exponential backoff is recommended.

Best practices

Playground

Troubleshooting