Skip to main content

Quickstart Guide

This guide walks you through submitting a video for analysis and retrieving the results. You will have structured metadata from your first video in under 15 minutes.

Prerequisites​

API key — choose the path that applies to you:

Sign up for Transcribe Pro Vision MAX at valossa.com/transcribe-video-to-text-ai — no sales call required. Once registered, log in to Valossa Portal → My Account → Subscriptions and API Keys to copy your key.

→ Full trial setup guide

Video URL — a publicly accessible direct link to a video file (MP4, MPEG, AVI, or other supported format).

Step 1: Submit a Video for Analysis​

Send a POST request to the new_job endpoint with your API key and the video URL.

curl​

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "media": {
      "video": {
        "url": "https://example.com/sample-video.mp4"
      }
    }
  }' \
  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/sample-video.mp4"
            }
        }
    }
)

data = response.json()
job_id = data["job_id"]
print(f"Job created: {job_id}")

JavaScript (Node.js / Browser fetch)​

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/sample-video.mp4"
      }
    }
  })
});

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

Response​

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

Save the job_id value. You will need it in the following steps.

Step 2: Check the Job Status​

Poll the job_status endpoint to monitor analysis progress. Analysis time depends on video length and complexity.

curl​

curl "https://api-eu.valossa.com/core/1.0/job_status?api_key=YOUR_API_KEY&job_id=167d6a67-fb99-438c-a44c-c22c98229b93"

Python​

import time

while True:
    status_response = requests.get(
        "https://api-eu.valossa.com/core/1.0/job_status",
        params={
            "api_key": "YOUR_API_KEY",
            "job_id": job_id
        }
    )
    status = status_response.json()
    print(f"Status: {status['status']}")

    if status["status"] == "finished":
        break
    elif status["status"] == "error":
        print(f"Job failed: {status}")
        break

    time.sleep(10)

JavaScript​

async function waitForCompletion(jobId) {
  while (true) {
    const res = await fetch(
      `https://api-eu.valossa.com/core/1.0/job_status?api_key=YOUR_API_KEY&job_id=${jobId}`
    );
    const status = await res.json();
    console.log("Status:", status.status);

    if (status.status === "finished") return status;
    if (status.status === "error") throw new Error("Job failed");

    await new Promise(resolve => setTimeout(resolve, 10000));
  }
}

await waitForCompletion(data.job_id);

Step 3: Download the Results​

Once the job status is finished, fetch the metadata JSON.

curl​

curl "https://api-eu.valossa.com/core/1.0/job_results?api_key=YOUR_API_KEY&job_id=167d6a67-fb99-438c-a44c-c22c98229b93" \
  -o results.json

Python​

results_response = requests.get(
    "https://api-eu.valossa.com/core/1.0/job_results",
    params={
        "api_key": "YOUR_API_KEY",
        "job_id": job_id
    }
)

metadata = results_response.json()

# Print detected visual concepts
if "visual.context" in metadata["detection_groupings"]["by_detection_type"]:
    for det_id in metadata["detection_groupings"]["by_detection_type"]["visual.context"][:10]:
        detection = metadata["detections"][det_id]
        print(f"Detected: {detection['label']}")

JavaScript​

const resultsRes = await fetch(
  `https://api-eu.valossa.com/core/1.0/job_results?api_key=YOUR_API_KEY&job_id=${data.job_id}`
);
const metadata = await resultsRes.json();

// Print detected visual concepts
const visualDetections = metadata.detection_groupings.by_detection_type["visual.context"] || [];
for (const detId of visualDetections.slice(0, 10)) {
  const detection = metadata.detections[detId];
  console.log("Detected:", detection.label);
}

Step 4: Explore Your Results​

The returned JSON contains several top-level sections:

SectionPurpose
version_infoMetadata format version and backend version
job_infoDetails about the analysis request
media_infoTechnical info about the video (duration, FPS)
detectionsAll detected concepts, faces, speech, topics, etc.
detection_groupingsOrganized views: by_detection_type, by_second, and more
segmentationsShot boundary detection data

For a detailed explanation of each section, see Core Concepts and JSON Structure.

Next Steps​