EN ▾

◆ API_REFERENCE

Seeknetic API Documentation

Use Seeknetic cloud APIs to generate embeddings and tags, manage collections, and perform semantic search workflows.

Authentication X-API-Key

Format application/json

API Endpoints by Region

Region	Base URL	Status
Tokyo, Japan	`https://api.jp.seeknetic.com`	Available
Oregon, USA	`https://api.us.seeknetic.com`	Coming Soon
Beijing, China	`https://api.cn.seeknetic.com`	Coming Soon

Authentication

All model service endpoints require API key authentication.

Using Your API Key

You can provide your API key in two ways:

Method 1: X-API-Key Header (Recommended)

curl https://api.jp.seeknetic.com/video_tagging \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json"

Method 2: Authorization Header

curl https://api.jp.seeknetic.com/video_tagging \
  -H "Authorization: Bearer {your_api_key}" \
  -H "Content-Type: application/json"

Video Embedding

Encode videos or text into vector embeddings for semantic search and similarity calculations.

POST /video_embedding/encode_video

Encode a video into embedding vectors (synchronous processing).

Request curl

Auth

X-API-Key

Content-Type

application/json

Body

{"video_url":"https://..."}

bash

curl -X POST "https://api.jp.seeknetic.com/video_embedding/encode_video" \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"video_url":"https://example.com/video.mp4"}'

Example python

python

import requests
import base64

# Using video URL
response = requests.post(
    "https://api.jp.seeknetic.com/video_embedding/encode_video",
    headers={
        "X-API-Key": "{your_api_key}",
        "Content-Type": "application/json"
    },
    json={"video_url": "https://example.com/video.mp4"}
)

result = response.json()
print(f"Embedding dimension: {len(result['embeddings'][0])}")

POST /video_embedding/encode_text

Encode text into embedding vectors for semantic search.

Use this endpoint to create query embeddings that can be compared against video embeddings.

Request curl

Auth

X-API-Key

Content-Type

application/json

Body

{"text":"..."}

bash

curl -X POST "https://api.jp.seeknetic.com/video_embedding/encode_text" \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"text":"A dog playing in the park"}'

Example python

python

import requests

response = requests.post(
    "https://api.jp.seeknetic.com/video_embedding/encode_text",
    headers={
        "X-API-Key": "{your_api_key}",
        "Content-Type": "application/json"
    },
    json={"text": "A dog playing in the park"}
)

result = response.json()
print(f"Text embedding dimension: {len(result['embedding'])}")

POST /video_embedding/encode_video/async

Submit video for asynchronous embedding extraction.

Request curl

Auth

X-API-Key

Content-Type

application/json

Body

{"video_url":"https://..."}

bash

curl -X POST "https://api.jp.seeknetic.com/video_embedding/encode_video/async" \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"video_url":"https://example.com/video.mp4"}'

Example python

python

import requests
import time

# 1. Submit async task
response = requests.post(
    "https://api.jp.seeknetic.com/video_embedding/encode_video/async",
    headers={
        "X-API-Key": "{your_api_key}",
        "Content-Type": "application/json"
    },
    json={"video_url": "https://example.com/video.mp4"}
)

request_id = response.json()["request_id"]
print(f"Task submitted, Request ID: {request_id}")

# 2. Poll status until completion
while True:
    status_response = requests.get(
        f"https://api.jp.seeknetic.com/async_status/{request_id}",
        headers={"X-API-Key": "{your_api_key}"}
    )

    status_data = status_response.json()
    status = status_data['status']

    if status == 'completed':
        embedding = status_data['embedding']
        print(f"Complete! Dimension: {len(embedding)}")
        break
    elif status == 'failed':
        print(f"Failed: {status_data['error_message']}")
        break

    time.sleep(2)

GET /async_status/{request_id}

Query the status and results of an asynchronous task.

Request curl

Auth

X-API-Key

Path Param

request_id

Status Flow:

pending

→

processing

→

completed

bash

curl -X GET "https://api.jp.seeknetic.com/async_status/{request_id}" \
  -H "X-API-Key: {your_api_key}"

Example python

python

import requests

request_id = "your_request_id_from_async_call"

response = requests.get(
    f"https://api.jp.seeknetic.com/async_status/{request_id}",
    headers={"X-API-Key": "{your_api_key}"}
)

status_data = response.json()
print(f"Status: {status_data['status']}")

if status_data['status'] == 'completed':
    print(f"Result: {status_data['embedding']}")

Video Tagging

Analyze video metadata including shot size, camera movement, shooting angle, and more.

POST /video_tagging

Analyze video and extract metadata (synchronous processing).

Supports both video URLs and Base64-encoded video data.

Request curl

Auth

X-API-Key

Content-Type

application/json

Body

{"video_url":"https://..."}

bash

curl -X POST "https://api.jp.seeknetic.com/video_tagging" \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"video_url":"https://example.com/video.mp4"}'

Example python

python

import requests

response = requests.post(
    "https://api.jp.seeknetic.com/video_tagging",
    headers={
        "X-API-Key": "{your_api_key}",
        "Content-Type": "application/json"
    },
    json={"video_url": "https://example.com/video.mp4"}
)

result = response.json()
print(f"Tags: {result['tags']}")

POST /video_tagging/async

Submit video for asynchronous tagging.

Request curl

Auth

X-API-Key

Content-Type

application/json

Body

{"video_url":"https://..."}

bash

curl -X POST "https://api.jp.seeknetic.com/video_tagging/async" \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"video_url":"https://example.com/video.mp4"}'

Example python

python

import requests

# Submit async tagging task
response = requests.post(
    "https://api.jp.seeknetic.com/video_tagging/async",
    headers={
        "X-API-Key": "{your_api_key}",
        "Content-Type": "application/json"
    },
    json={"video_url": "https://example.com/video.mp4"}
)

request_id = response.json()["request_id"]
print(f"Tagging task submitted, Request ID: {request_id}")

Video Management

Video management service provides video collection management and semantic search capabilities.

Collections

POST /collections

Create a new video collection.

Request curl

Auth

X-API-Key

Content-Type

application/json

Body

{"name":"...","description":"..."}

bash

curl -X POST "https://api.jp.seeknetic.com/collections" \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Video Collection","description":"Test collection"}'

Example python

python

import requests

response = requests.post(
    "https://api.jp.seeknetic.com/collections",
    headers={
        "X-API-Key": "{your_api_key}",
        "Content-Type": "application/json"
    },
    json={
        "name": "My Video Collection",
        "description": "Test collection"
    }
)

result = response.json()
print(f"Collection ID: {result['collection_id']}")

GET /collections

List all video collections.

Request curl

Auth

X-API-Key

bash

curl -X GET "https://api.jp.seeknetic.com/collections" \
  -H "X-API-Key: {your_api_key}"

Example python

python

import requests

response = requests.get(
    "https://api.jp.seeknetic.com/collections",
    headers={"X-API-Key": "{your_api_key}"}
)

collections = response.json()
for collection in collections:
    print(f"Collection: {collection['name']} (ID: {collection['id']})")

POST /collections/{collection_id}/search

Search for similar video clips in a collection (semantic vector search).

Request curl

Auth

X-API-Key

Content-Type

application/json

Path Param

collection_id

Body

{"text":"...","top_k":10}

bash

curl -X POST "https://api.jp.seeknetic.com/collections/{collection_id}/search" \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"text":"A dog playing in the park","top_k":10}'

Example python

python

collection_id = "3d146cd7-4ecb-4dca-bf97-a271a143ee44"

response = requests.post(
    f"https://api.jp.seeknetic.com/collections/{collection_id}/search",
    headers={
        "X-API-Key": "{your_api_key}",
        "Content-Type": "application/json"
    },
    json={
        "text": "A dog playing in the park",
        "top_k": 10
    }
)

for result in response.json()['results']:
    print(f"Video: {result['video_id']}, Similarity: {result['similarity']:.2f}")

Videos

Video upload and processing use an asynchronous processing model.

POST /collections/{collection_id}/videos/upload

Upload video file directly (recommended for files < 100MB).

Request curl

Auth

X-API-Key

Content-Type

multipart/form-data

Path Param

collection_id

Body

file (multipart)

bash

curl -X POST "https://api.jp.seeknetic.com/collections/{collection_id}/videos/upload" \
  -H "X-API-Key: {your_api_key}" \
  -F "file=@video.mp4"

Example python

python

import requests

collection_id = "your_collection_id"

with open("video.mp4", "rb") as video_file:
    files = {"file": video_file}
    response = requests.post(
        f"https://api.jp.seeknetic.com/collections/{collection_id}/videos/upload",
        headers={"X-API-Key": "{your_api_key}"},
        files=files
    )

result = response.json()
print(f"Video uploaded, ID: {result['video_id']}")

GET /videos/{video_id}/status

Lightweight status query for monitoring video processing progress.

Request curl

Auth

X-API-Key

Path Param

video_id

bash

curl -X GET "https://api.jp.seeknetic.com/videos/{video_id}/status" \
  -H "X-API-Key: {your_api_key}"

Processing Stages:

uploaded: Waiting for processing
processing: Processing in progress
processed: Processing complete
failed: Processing failed

Example python

python

import requests

video_id = "your_video_id"

response = requests.get(
    f"https://api.jp.seeknetic.com/videos/{video_id}/status",
    headers={"X-API-Key": "{your_api_key}"}
)

status_data = response.json()
print(f"Status: {status_data['status']}")
print(f"Progress: {status_data.get('progress', 'N/A')}%")

Error Handling

Common Error Codes

Status Code	Description	Solution
400	Bad request parameters	Check request JSON format and required fields
401	Invalid API key	Check if API key is correct
404	Resource not found	Check URL path and resource ID
429	Rate limit exceeded	Reduce request frequency or upgrade plan
500	Internal server error	Contact technical support
502	External API error	External service temporarily unavailable, retry later
504	Request timeout	Try async interface or smaller video

Rate Limiting

Each API key has independent rate limits (QPS - Queries Per Second)
Rate limits are set when creating the API key
Exceeding limits will return a 429 error