API Overview

The Valossa Core API is a REST API for submitting video analysis jobs, monitoring their progress, and retrieving structured metadata results.

Base URL

https://api-eu.valossa.com/core/1.0/

All requests must use HTTPS. Unencrypted HTTP is not supported.

Authentication

Every request requires a valid API key. See Authentication for details on obtaining and using your API key.

• POST requests: Include api_key in the JSON request body.
• GET requests: Pass api_key as a query parameter.

Response Format

All responses are returned as JSON. Successful responses return HTTP status code 200. Error responses return a non-200 HTTP status code with an errors array in the JSON body. See Error Codes for details.

Endpoints

The Core API provides nine endpoints:

Method	Endpoint	Description
POST	/new_job	Submit a new video for analysis
GET	/job_status	Check the status of an analysis job
GET	/job_results	Download the metadata results of a finished job
GET	/list_jobs	List all jobs for a given API key
POST	/cancel_job	Cancel a job that is still in the waiting queue
POST	/delete_job	Delete a job and its associated assets
POST	/initialize_file_upload	Initialize chunked video upload
POST	/send_file_chunk	Send one chunk of an upload
POST	/finalize_file_upload	Finalize upload and get valossaupload:// URL

Training API Endpoints

Face training and gallery management use a separate base URL:

https://api-eu.valossa.com/training/1.0/

See Face Training API for all training routes:

• POST /upload_image
• POST /create_face_gallery
• POST /update_face_gallery
• GET /list_face_galleries
• POST /create_face_identity
• POST /add_face_image
• GET /list_face_identities
• GET /list_face_images
• POST /update_face_identity
• POST /remove_face_image
• POST /remove_face_identity

Typical Workflow

1. POST /new_job        --> Returns job_id
2. GET  /job_status     --> Poll until status is "finished"
3. GET  /job_results    --> Download metadata JSON

Speech Analysis Notes

When working with speech-related features, keep the following in mind:

• If you provide a pre-existing SRT transcript with your video, the system will analyze the transcript content instead of performing automatic speech-to-text. Results will appear in transcript.* detection types.
• If no transcript is provided, the system performs automatic speech-to-text and keyword extraction. Results appear in audio.* detection types.
• Audio context detection (audio.context) is always performed regardless of whether a transcript is provided.
• Transcript-only analysis (SRT without a video file) is supported with special configuration.

API Spec & Tooling

Download the machine-readable API specification and ready-to-use Postman collection:

Resource	Description
OpenAPI 3.1.0 spec	Formal API spec — import into any OpenAPI-compatible tool, code generator, or Swagger UI
Postman Collection	8 pre-configured requests with auto-saved job_id variable — import directly into Postman

Import into Postman

1. Open Postman → Import → paste the URL: https://docs.valossa.com/valossa-api.postman_collection.json
2. Set the api_key collection variable to your API key
3. The job_id variable is automatically saved after a successful new_job call

Related Resources

• Authentication — API key management
• Input Formats — Supported video formats and limits
• Error Codes — Error response format and common errors
• Training API Overview — Face Training API for custom face galleries