Build with video intelligence.
The published Seeknetic API supports text embeddings, asynchronous video embeddings, tensor uploads, and professional shot tagging.
Authentication
Provide your API key in the X-API-Key header. Create or manage your key in your Seeknetic account.
The published API also supports Authorization: Bearer <API_KEY> as an alternative to X-API-Key. Use one authentication method per request.
Base URL: https://api.seeknetic.com
Code, API identifiers, and request values retain their original technical language.
Text embedding
Encode a text query into an embedding for semantic comparison with your indexed media.
/video_embedding/encode_text 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"}'Python / Example
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'])}")Video embedding
Submit a hosted video for asynchronous encoding. Save the returned request_id and poll for the result.
For preprocessed inputs, use tensor.video_input_key and tensor.audio_input_key returned by the tensor-upload endpoint.
/video_embedding/encode_video/async 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"}'Python / Example
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)Tensor upload
Upload preprocessed video and audio tensors, then reference the returned input keys in the asynchronous model request.
/files/upload/tensors 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"}
}'Python / Example
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())Shot tagging
Submit a video for asynchronous professional shot metadata generation.
For preprocessed tagging inputs, use tensor.video_input_key and tensor.video_kwargs_key returned by the tensor-upload endpoint.
/video_tagging/async 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"}'Python / Example
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}")Async task status
Check a submitted request. Continue polling while it is pending or processing, and inspect the result when completed.
Task states: pending → processing → completed. A failed task includes an error_message.
/async_status/{request_id} curl -X GET "https://api.seeknetic.com/async_status/{request_id}" \
-H "X-API-Key: {your_api_key}"Python / Example
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']}")Errors & retries
Check input parameters for 400 responses and credentials for 401. Back off after 429. Retry transient server errors with a bounded retry strategy.
| HTTP status | Meaning | What to do |
|---|---|---|
| 400 | Invalid request | Check the JSON body and required fields. |
| 401 | Authentication failed | Check the API key. Do not expose it in client-side code. |
| 402 | Quota exceeded | Check usage and billing before retrying. |
| 413 | Payload too large | Reduce the payload or use smaller tensor uploads. |
| 422 | Validation failed | Check field types and the endpoint request schema. |
| 429 | Rate limit exceeded | Reduce request frequency; retry with backoff. |
| 500 | Internal service error | Retry with a fixed attempt limit. Contact support if it persists. |
| 502 | Upstream service error | Wait before retrying with a fixed attempt limit. |
| 504 | Request timeout | Use the async workflow or a smaller input. Check task status before resubmitting. |
Rate limits
Each API key has its own QPS limit, configured when the key is created. Exceeding it returns HTTP 429.