POST /new_job

Creates a new video analysis job. The system downloads the video from the provided URL and begins processing it with the AI features enabled by your subscription.

Endpoint

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

Request Body

The request body must be a JSON object with the following fields:

Field	Type	Required	Description
api_key	string	Yes	Your Valossa API key
media	object	Yes	Media configuration object
media.video	object	Yes	Video source configuration
media.video.url	string	Yes	Direct URL to the video file (HTTPS recommended)
media.transcript	object	No	Pre-existing transcript configuration
media.transcript.url	string	No	URL to an SRT transcript file
media.customer_media_info.id	string	No	Your own media identifier to later query by customer media ID
media.description	string	No	Text description of the video (analyzed for keywords)
media.title	string	No	Title of the video
media.language	string	No	Language code (default: en-US). See Supported Languages.
analysis_parameters	object	No	Optional fine-tuning parameters for analysis
analysis_parameters.face_min_relative_height	number	No	Minimum face height as a fraction of frame height (0–1) to be detected. Lower values detect smaller faces at the cost of more false positives.
analysis_parameters.face_galleries.custom_gallery.id	string	No	Non-default custom gallery ID for face recognition
email_notification.to_group	string	No	Email notifications group (users_with_access_to_api_key_results)
callback.url	string	No	Callback URL for an HTTP POST notification when job reaches an end state

Video Delivery Options

• URL download: Provide a direct link to a video file. Supports HTTP/HTTPS, AWS S3 (with configuration), Google Drive, and Dropbox (with correct sharing settings).
• Upload via API: Use the upload-related API functions to upload a file, then reference the generated valossaupload:// URL.
• Upload via Portal: Use the Analyze page in Valossa Portal for manual uploads.

Response

A successful response returns HTTP 200 with a JSON body containing:

Field	Type	Description
job_id	string	UUID identifying the created analysis job

Examples

Minimal Request

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

Full Request with All Options

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "media": {
      "video": {
        "url": "https://example.com/video.mp4"
      },
      "transcript": {
        "url": "https://example.com/subtitles.srt"
      },
      "description": "A documentary about marine biology",
      "title": "Ocean Depths",
      "language": "en-US"
    }
  }' \
  https://api-eu.valossa.com/core/1.0/new_job

Python

import requests

response = requests.post(
    "https://api-eu.valossa.com/core/1.0/new_job",
    json={
        "api_key": "YOUR_API_KEY",
        "media": {
            "video": {
                "url": "https://example.com/video.mp4"
            },
            "language": "en-US",
            "title": "My Video"
        }
    }
)

result = response.json()
print(f"Job ID: {result['job_id']}")

JavaScript

const response = await fetch("https://api-eu.valossa.com/core/1.0/new_job", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "YOUR_API_KEY",
    media: {
      video: { url: "https://example.com/video.mp4" },
      language: "en-US",
      title: "My Video"
    }
  })
});

const result = await response.json();
console.log("Job ID:", result.job_id);

Response

{
  "job_id": "167d6a67-fb99-438c-a44c-c22c98229b93"
}

Notes

• The video file is downloaded asynchronously after the job is created. There may be a delay between job creation and the start of the download.
• Avoid using expiring URLs. If you must, set a long expiration time.
• The AI features used for analysis are determined by the subscription bound to your API key.
• If you provide a pre-existing transcript, audio-based speech detection is skipped (but audio.context detection still runs).
• For language-specific behavior and restrictions, see Supported Languages.

Error Responses

See Error Codes for the error response format. Common errors for this endpoint include:

• Invalid or missing API key
• Missing media.video.url field
• Malformed JSON request body