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

For production integration, we strongly recommend using the official SDKs first, then fallback to direct HTTP APIs when needed.

API Endpoints by Region

Region	Base URL	Status
Tokyo, Japan	`https://api.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.seeknetic.com/video_tagging \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json"

Method 2: Authorization Header

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

File Upload

/files/upload/tensors is a standalone upload API. It is not part of embedding or tagging endpoints.

POST /files/upload/tensors

Upload preprocessed tensor JSON (embedding/tagging) and get r2_keys for later async API calls.

Request curl

Auth

X-API-Key or Authorization: Bearer

Content-Type

application/json

Body

{"service","video_input/audio_input/video_kwargs","request_id"}

bash

curl -X POST "https://api.seeknetic.com/files/upload/tensors" \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "service":"embedding",
    "request_id":"emb-task-0001",
    "video_input":{"data":"AAAB...","shape":[1,12,3,224,224],"dtype":"uint8"},
    "audio_input":{"data":"AAAB...","shape":[1,1,220500],"dtype":"float32"}
  }'

Example python

python

import requests

response = requests.post(
    "https://api.seeknetic.com/files/upload/tensors",
    headers={
        "X-API-Key": "{your_api_key}",
        "Content-Type": "application/json"
    },
    json={
        "service": "embedding",
        "request_id": "emb-task-0001",
        "video_input": {
            "data": "AAAB...",
            "shape": [1, 12, 3, 224, 224],
            "dtype": "uint8"
        },
        "audio_input": {
            "data": "AAAB...",
            "shape": [1, 1, 220500],
            "dtype": "float32"
        }
    }
)

print(response.json())

Video Embedding

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

If you use tensor mode here, first upload tensor payloads via /files/upload/tensors.

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

Also supports tensor mode: tensor.video_input_key / tensor.audio_input_key (from /files/upload/tensors).

Request curl

Auth

X-API-Key

Content-Type

application/json

Body

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

bash

curl -X POST "https://api.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.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.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.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.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/async

Submit video for asynchronous tagging.

Also supports tensor mode: tensor.video_input_key / tensor.video_kwargs_key (from /files/upload/tensors).

Request curl

Auth

X-API-Key

Content-Type

application/json

Body

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

bash

curl -X POST "https://api.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.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}")

GET /async_status/{request_id}

Check tagging async task status by request ID. Returns the same status schema as embedding async status.

Request curl

Auth

X-API-Key

Path Param

request_id

bash

curl -X GET "https://api.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.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']}")

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
402	Quota exceeded	Check usage and billing status, then retry with available quota.
413	Payload too large	Reduce request size or upload tensors in smaller chunks.
422	Validation error	Verify required fields and schema format based on OpenAPI request model.
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