tupicInsights
Developers

API Documentation

Complete reference for the Tupic Insights REST API. Create assets, authenticate users, search by similarity, and trigger analysis workflows from your own systems.

Base URL: https://api.tupic.com/insights/v1

Authentication

All protected endpoints require a bearer token. Obtain a JWT via/auth/signinor create a personal access token from the dashboard and send it asAuthorization: Bearer YOUR_TOKEN.

Auth

POST/auth/signupRegister a new account
Request Body
{
  "username": "john",
  "email": "john@example.com",
  "password": "securepass123"
}
Response 201
{
  "access_token": "eyJ...",
  "user": { "id": 1, "username": "john" }
}
POST/auth/signinLogin and receive a JWT
Request Body
{
  "username": "john",
  "password": "securepass123"
}
Response 200
{ "access_token": "eyJ..." }
GET/auth/meCurrent user profile
Response 200
{ "user": { "id": 1, "username": "john", "email": "john@example.com" } }
POST/auth/googleGoogle Sign-In

Verifies a Google ID token and signs the user in. New users are created automatically if they do not already exist.

Request Body
{ "credential": "Google ID token" }

Personal Access Tokens

POST/tokensCreate a PAT
Request Body
{ "name": "my-bot-token" }
Response 201
{
  "id": 5,
  "access_token": "eyJ...",
  "name": "my-bot-token"
}
GET/tokensList active tokens
Response 200
{ "tokens": [{ "id": 5, "name": "my-bot-token" }] }
DEL/tokens/{id}Revoke a token
Response 200
{ "message": "Token deleted" }

Assets and Library

POSThttps://api.tupic.com/assets/v1/assetsCreate asset and receive upload URL

Create an asset in the asset service first. The response returns an upload_url that must be used in a separate PUT request to upload the raw binary file.

ParamTypeDescription
namestringAsset name. In the dashboard this is the selected file name.
descriptionstringAsset description. In the dashboard this is also the selected file name.
mime_typestringMIME type of the selected file, for example image/jpeg.
license_typestringRequired asset license type. The dashboard sends free.
Binary Upload
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@photo.jpg"
Response 201
{
  "asset": {
    "id": "a1b2c3",
    "name": "photo.jpg",
    "media_type": "image",
    "status": "created"
  },
  "upload_url": "https://..."
}
GET/assetsList uploaded assets
ParamTypeDescription
typestringOptional filter: image, video, audio, or text.
Response 200
[
  {
    "id": "a1b2c3",
    "name": "photo.jpg",
    "media_type": "image",
    "thumbnails": { "small": "https://..." }
  }
]
GET/assets/status/{asset_id}Check asset processing status
ParamTypeDescription
asset_idstringAsset identifier returned by the asset service.
DEL/assets/{asset_id}Delete an asset record
ParamTypeDescription
asset_idstringAsset identifier to delete from Insights.
Response 200
{ "message": "Content deleted successfully" }

Search and Similarity

GET/search?query={q}Text and hashtag search
Response 200
{ "query": "car", "count": 3, "results": [...] }
POST/search/imageVisual similarity search
Response 200
{ "results": [{ "id": 15, "similarity": 87.3 }] }
GET/analyze/recommend/{id}Recommendations
Response 200
[{ "id": 15, "cosine_similarity": 82.5, "total_score": 0.925 }]

Video Analysis

POST/analyze/video/{id}Scene-by-scene analysis
Response 200
[{ "scene_id": 25, "frame_time": 1.0, "hashtags": ["person"], "rga": "G" }]
POST/analyze/ad/{id}Ad placement intelligence
Response 200
[{ "scene_id": 3, "saliency_score": 0.45, "emotion": "happy", "score": 0.78, "is_best": true }]
POST/analyze/apply_cutCut video intervals
Request Body
{ "filename": "video.mp4", "intervals": [[5.0, 12.0]] }

Subtitles

POST/subtitle/generate/{id}Generate subtitles
Request Body
{ "target_language": "en" }
Response 200
{
  "srt_file": "https://...",
  "job_id": "uuid",
  "detected_language": "fa"
}
GET/subtitle/status?job_id={id}Subtitle job progress
Response 200
{ "progress": 70, "log": "Processing chunk 2/3..." }

File Access

GET/storage/{path}Serve uploaded files

Uploaded files, thumbnails, and generated asset outputs are available through the storage routes, subject to platform permissions and retention rules.