English 简体中文 繁體中文

Seeknetic API Documentation

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

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).

Python Example:

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.

Python Example:

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.

Python Example:

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.

Status Flow:

pending
→
processing
→
completed

Python Example:

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.

Python Example:

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.

Python Example:

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.

Python Example:

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.

Python Example:

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).

Python Example:

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).

Python Example:

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.

Processing Stages:

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

    • Python Example:

    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