Text to Video (with Metadata Filters)

POST https://api.coactive.ai/api/v0/search/metadata-filters/text-to-video
Content-Type: application/json

Triggers an asynchronous text-to-video search within the specified dataset (dataset_id), restricted to assets matching every entry in metadata_filters (e.g., genre = musical, rating != PG, headline contains olympics, impressions > 1000). The text_query is encoded into an embedding using the dataset’s configured vision-language encoder (e.g., CLIP, SigLIP, Perception Encoder) and ranked against video keyframe embeddings via vector similarity, while the metadata filters are applied as a pre-scoring constraint on the asset metadata fields. Returns the Databricks run_id immediately; use the status and result endpoints to poll for the final ranked list of videos (each with the parent video, top composite slice, top keyframe, metadata, score, and optional moderation score).

Authentication

• Authorization header (bearer token, required) — Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

Body (application/json)

This endpoint expects an object.

• dataset_id (string, required) — Dataset to search within
• text_query (string, required) — Natural language query encoded into an embedding to score visual content via vector similarity.
• limit (integer, optional, default: 40) — Max number of results to return
• offset (integer, optional, default: 0) — Number of results to skip before returning
• metadata_filters (list of object, optional) — List of filter objects applied against asset metadata fields before scoring. All filters are combined with AND.
  • key (string, required) — Name of the metadata field to filter on (must exist on the dataset’s assets).
  • value (string, required) — Value to compare the metadata field against. Always provided as a string; numerical operators (>, <, >=, <=) parse it as a number.
  • op (enum, optional) — Comparison operator. Defaults to = (equality).
    • Allowed values: =, !=, contains, >, <, >=, <=
• skip_moderation (boolean, optional, default: false) — When true, moderation scoring is skipped and moderation_score will be null on all results.

Response

200

Successful Response

• run_id (integer, required) — Databricks job run ID to use for status polling and result retrieval

Errors

422 Unprocessable Entity Error

Validation Error

• detail (list of object, optional)
  • loc (list of string or integer, required)
  • msg (string, required)
  • type (string, required)

Examples

Request

{
  "dataset_id": "11973632-462e-4e14-a744-181b28ea931d",
  "text_query": "live concert performance"
}

Response

{
  "run_id": 452378
}

SDK Code

import requests

url = "https://api.coactive.ai/api/v0/search/metadata-filters/text-to-video"

payload = {
    "dataset_id": "11973632-462e-4e14-a744-181b28ea931d",
    "text_query": "live concert performance"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

const url = 'https://api.coactive.ai/api/v0/search/metadata-filters/text-to-video';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"dataset_id":"11973632-462e-4e14-a744-181b28ea931d","text_query":"live concert performance"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "https://api.coactive.ai/api/v0/search/metadata-filters/text-to-video"

  payload := strings.NewReader("{\n  \"dataset_id\": \"11973632-462e-4e14-a744-181b28ea931d\",\n  \"text_query\": \"live concert performance\"\n}")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Authorization", "Bearer <token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.coactive.ai/api/v0/search/metadata-filters/text-to-video")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"dataset_id\": \"11973632-462e-4e14-a744-181b28ea931d\",\n  \"text_query\": \"live concert performance\"\n}"

response = http.request(request)
puts response.read_body

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.coactive.ai/api/v0/search/metadata-filters/text-to-video")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"dataset_id\": \"11973632-462e-4e14-a744-181b28ea931d\",\n  \"text_query\": \"live concert performance\"\n}")
  .asString();

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.coactive.ai/api/v0/search/metadata-filters/text-to-video', [
  'body' => '{
  "dataset_id": "11973632-462e-4e14-a744-181b28ea931d",
  "text_query": "live concert performance"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();

using RestSharp;

var client = new RestClient("https://api.coactive.ai/api/v0/search/metadata-filters/text-to-video");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"dataset_id\": \"11973632-462e-4e14-a744-181b28ea931d\",\n  \"text_query\": \"live concert performance\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "dataset_id": "11973632-462e-4e14-a744-181b28ea931d",
  "text_query": "live concert performance"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.coactive.ai/api/v0/search/metadata-filters/text-to-video")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()