# Valossa AI — Video Analysis API

> Valossa AI is a REST API for automated video content analysis. It analyzes video files and returns structured JSON metadata containing time-coded detections for objects, faces, speech, audio events, topics, emotions, OCR text, and content compliance signals.

## Product

- Company: Valossa Labs Oy (Finland)
- Website: https://valossa.com
- Documentation: https://docs.valossa.com
- Portal: https://portal-eu.valossa.com
- API base URL: https://api-eu.valossa.com/core/1.0/
- OpenAPI spec: https://docs.valossa.com/openapi.yaml
- Free trial (self-serve): https://valossa.com/transcribe-video-to-text-ai/

## Core Capabilities

- Visual object and scene detection (visual.context) — thousands of categories
- Face detection and celebrity recognition (human.face) — with custom gallery training
- Speech-to-text transcription (audio.speech) — 23 languages, SRT/VTT export
- Speech keyword and named entity extraction (audio.keyword.*)
- Audio event detection (audio.context) — music, applause, gunshots, etc.
- Content moderation — visual, audio, and speech compliance signals
- Emotion and sentiment analysis — face valence, ranked facial expressions, speech sentiment, voice prosodics
- IAB Content Taxonomy v2.2 categorization (topic.iab, topic.iab.section)
- Ad suitability scoring (Ad Score) — for contextual advertising
- OCR — visual text recognition in video frames (visual.text_region.*)
- Localized objects with bounding boxes (visual.object.localized)
- Face bounding boxes (frames_faces metadata)
- Shot boundary detection (segmentations)
- Video auto-summarization clips (Autopreview — separate subscription)

## API Overview

**Authentication:** API key passed as `api_key` in request body (POST) or query string (GET).

**9 Core API endpoints:**
1. POST /new_job — Submit video for analysis, returns job_id UUID
2. GET /job_status — Poll job status (queued/on_hold/preparing_analysis/processing/finished/error)
3. GET /job_results — Download metadata JSON when finished
4. GET /list_jobs — List all jobs for an API key
5. POST /cancel_job — Cancel a queued or processing job
6. POST /delete_job — Delete job and associated assets
7. POST /initialize_file_upload — Initialize chunked file upload
8. POST /send_file_chunk — Upload one chunk
9. POST /finalize_file_upload — Finalize upload and receive `valossaupload://` URL

**Input limits:** 7 GB max file size, 5 hours max duration, 4096px max vertical resolution.
**Supported formats:** MP4 (H.264 recommended), MPEG, AVI, FLV, WebM, and others.
**Video sources:** HTTP/HTTPS URL, Google Drive, Dropbox, AWS S3 (on request), direct upload.

## Getting Started (Self-Serve)

1. Sign up at https://valossa.com/transcribe-video-to-text-ai/ (no sales call needed)
2. Log in to https://portal-eu.valossa.com → My Account → Subscriptions and API Keys
3. Copy your API key
4. Submit your first video:

```bash
curl -X POST -H "Content-Type: application/json" \
  -d '{"api_key":"YOUR_KEY","media":{"video":{"url":"https://example.com/video.mp4"}}}' \
  https://api-eu.valossa.com/core/1.0/new_job
```

5. Poll status: GET /job_status?api_key=YOUR_KEY&job_id=JOB_ID
6. Download results: GET /job_results?api_key=YOUR_KEY&job_id=JOB_ID

## Metadata Output Format

Results are returned as Valossa Core Metadata JSON (current version: 1.8.1).
Top-level structure:
- version_info — format version, backend version, metadata type
- job_info — job ID and original request parameters
- media_info — video duration, fps, customer-provided title
- detections — associative array keyed by detection ID; each detection has: t (type), label, cid, ext_refs (Wikidata/GKG/IAB), categ, occs (occurrences with start/end seconds), a (attributes)
- detection_groupings — by_detection_type (relevance-sorted), by_second (temporal index with per-second attributes such as face `sen`/`sz`, voice `val`/`aro`, color `rgb`), by_detection_property, by_frequency
- segmentations — shot boundary data

Additional metadata types (separate downloads): frames_faces (face bounding boxes), seconds_objects (object bounding boxes), frames_objects (per-frame object coords), speech_to_text_srt, speech_to_text_vtt, speech_to_text_ttml, speech_to_text_avid_txt (subtitle formats), visual_captions (scene descriptions in `selected_sections` using `section.s_start` / `section.s_end`).

## Detection Types (38 active)

Visual (8): visual.context, visual.color, visual.object.localized, visual.text_region.full_frame_analysis, visual.text_region.lower_third, visual.text_region.middle_third, visual.text_region.upper_third, visual.text_region.keyword.compliance
Audio (13): audio.context, audio.speech, audio.speech_detailed, audio.speech_detailed.stats, audio.speech_summary, audio.speech_summary.keyword, audio.voice_emotion, audio.keyword.novelty_word, audio.keyword.name.person, audio.keyword.name.location, audio.keyword.name.organization, audio.keyword.name.general, audio.keyword.compliance
Human (2): human.face, human.face_group
Transcript (6): transcript.keyword.novelty_word, transcript.keyword.name.person, transcript.keyword.name.location, transcript.keyword.name.organization, transcript.keyword.name.general, transcript.keyword.compliance
Topics (4): topic.iab, topic.iab.section, topic.general, topic.genre
External (5): external.keyword.novelty_word, external.keyword.name.person, external.keyword.name.location, external.keyword.name.organization, external.keyword.name.general

Note: Several deprecated types may still appear in older metadata (topic.iab.audio, topic.iab.transcript, topic.iab.visual, explicit_content.audio.offensive, explicit_content.transcript.offensive). See detection types documentation for details.

## Subscriptions

- Transcribe Pro Vision MAX (self-serve trial): All features except Ad Score and Autopreview
- AdScout: Adds topic.iab.section with Ad Score for programmatic advertising
- Autopreview: Automated video clip generation
- Custom/Enterprise: Volume pricing, on-premises Docker deployment

## Documentation Sections

### Getting Started
- Introduction: https://docs.valossa.com/getting-started/introduction
- Free Trial Setup: https://docs.valossa.com/getting-started/free-trial
- Quickstart Guide: https://docs.valossa.com/getting-started/quickstart
- Authentication: https://docs.valossa.com/getting-started/authentication
- Core Concepts: https://docs.valossa.com/getting-started/core-concepts
- Input Formats: https://docs.valossa.com/getting-started/input-formats
- Supported Languages: https://docs.valossa.com/getting-started/languages

### API Reference
- API Overview: https://docs.valossa.com/api-reference/overview
- POST /new_job: https://docs.valossa.com/api-reference/new-job
- GET /job_status: https://docs.valossa.com/api-reference/job-status
- GET /job_results: https://docs.valossa.com/api-reference/job-results
- GET /list_jobs: https://docs.valossa.com/api-reference/list-jobs
- POST /cancel_job: https://docs.valossa.com/api-reference/cancel-job
- POST /delete_job: https://docs.valossa.com/api-reference/delete-job
- POST /initialize_file_upload: https://docs.valossa.com/api-reference/initialize-file-upload
- POST /send_file_chunk: https://docs.valossa.com/api-reference/send-file-chunk
- POST /finalize_file_upload: https://docs.valossa.com/api-reference/finalize-file-upload
- Error Codes: https://docs.valossa.com/api-reference/error-codes
- Training API: https://docs.valossa.com/api-reference/training-overview
- POST /upload_image: https://docs.valossa.com/api-reference/upload-image
- POST /create_face_gallery: https://docs.valossa.com/api-reference/create-face-gallery
- POST /update_face_gallery: https://docs.valossa.com/api-reference/update-face-gallery
- GET /list_face_galleries: https://docs.valossa.com/api-reference/list-face-galleries
- POST /create_face_identity: https://docs.valossa.com/api-reference/create-face-identity
- POST /add_face_image: https://docs.valossa.com/api-reference/add-face-image
- GET /list_face_identities: https://docs.valossa.com/api-reference/list-face-identities
- GET /list_face_images: https://docs.valossa.com/api-reference/list-face-images
- POST /update_face_identity: https://docs.valossa.com/api-reference/update-face-identity
- POST /remove_face_image: https://docs.valossa.com/api-reference/remove-face-image
- POST /remove_face_identity: https://docs.valossa.com/api-reference/remove-face-identity

### Metadata Reference
- Metadata Overview: https://docs.valossa.com/metadata/overview
- JSON Structure: https://docs.valossa.com/metadata/json-structure
- Detection Types: https://docs.valossa.com/metadata/detection-types
- Occurrences: https://docs.valossa.com/metadata/occurrences
- Detection Categories: https://docs.valossa.com/metadata/detection-categories
- IAB Categories: https://docs.valossa.com/metadata/iab-categories
- Faces & Identity: https://docs.valossa.com/metadata/faces-identity
- Speech & Transcription: https://docs.valossa.com/metadata/speech-transcription
- Sentiment & Emotion: https://docs.valossa.com/metadata/sentiment-emotion
- Localized Objects: https://docs.valossa.com/metadata/localized-objects
- Segmentation & Shots: https://docs.valossa.com/metadata/segmentation-shots

### How-To Guides
- Content Moderation: https://docs.valossa.com/guides/content-moderation
- Video Tagging: https://docs.valossa.com/guides/video-tagging
- Face Recognition: https://docs.valossa.com/guides/face-recognition
- Speech-to-Text: https://docs.valossa.com/guides/speech-to-text
- IAB & Ad Suitability: https://docs.valossa.com/guides/iab-ad-suitability
- Emotion Analysis: https://docs.valossa.com/guides/emotion-analysis

### Tools & Apps
- Metadata Reader: https://docs.valossa.com/sdk-tools/metadata-reader
- Code Examples: https://docs.valossa.com/sdk-tools/code-examples
- Portal Tools: https://docs.valossa.com/sdk-tools/portal-tools
- Valossa Assistant: https://docs.valossa.com/sdk-tools/valossa-assistant

### Resources
- FAQ: https://docs.valossa.com/resources/faq
- Glossary: https://docs.valossa.com/resources/glossary

## Valossa Assistant — Conversational AI for Video

Valossa Assistant (https://valossa.com/video-ai-assistant/) is a conversational AI video analysis service — a no-code interface to the same Valossa AI engine that powers the API. Users can analyze videos, ask questions about content in natural language, search transcripts, extract clips, download captions and scene descriptions, and generate reports. It supports video question answering, video RAG (retrieval-augmented generation), transcript search, clip extraction, content compliance scanning, and document generation from video data. Designed for media professionals, content teams, and compliance officers who need video insights without writing code.

### Machine-Readable Resources
- OpenAPI 3.1.0 spec: https://docs.valossa.com/openapi.yaml
- Postman collection: https://docs.valossa.com/valossa-api.postman_collection.json
- Sitemap: https://docs.valossa.com/sitemap.xml