MediaLayer API docs

The MediaLayer Match API compares two pieces of media — image, video, or audio — and returns a similarity score, a confidence label, and (for video and audio) aligned matched segments. All three endpoints share one request shape and one response envelope.

Public usage is distributed exclusively through RapidAPI. Enterprise customers can request direct API access with custom rate limits and private deployment options — see Enterprise direct API.

To call any endpoint, you need a RapidAPI account and an active subscription to the MediaLayer listing. There is no separate signup on medialayer.ai — RapidAPI handles keys, plans, billing, and per-key quotas for public users.

Open the MediaLayer listing on RapidAPI →

1. Create a free RapidAPI account at rapidapi.com (no credit card required for the free tier).
2. Open the MediaLayer listing and click the Pricing tab.
3. Pick a plan that matches your expected monthly call volume. Free plans are available for evaluation.
4. Click Subscribe. Paid plans require a payment method on file with RapidAPI.

1. In the RapidAPI dashboard, open the MediaLayer listing and click the Endpoints tab.
2. Look at the Code Snippets panel — yourx-rapidapi-key is shown in the example headers for the active app.
3. To rotate or manage keys, go to My Apps → select an app → Security.

Treat the key as a secret. Never embed it in client-side JavaScript, public repos, or shipped mobile apps — proxy through your own backend instead.

Every request must include three headers:

x-rapidapi-key: YOUR_RAPIDAPI_KEY
x-rapidapi-host: medialayer-image-audio-video-matching-api.p.rapidapi.com
Content-Type: application/json

• POST /image/match
• POST /video/match
• POST /audio/match

Base URL: https://medialayer-image-audio-video-matching-api.p.rapidapi.com

All three endpoints accept the same JSON body. Both URLs must be public, http or https, and reachable from the internet.

{
  "source_url": "https://example.com/source.jpg",
  "target_url": "https://example.com/target.jpg"
}

• source_url — string, required. The reference asset.
• target_url — string, required. The asset being compared against the source.

Every successful response carries the same envelope. For images, matched_segments is always an empty array. For video and audio, it contains aligned segments with start/end timestamps in seconds.

{
  "match": true,
  "confidence": "high",
  "similarity_score": 0.92,
  "processing_time_ms": 38,
  "media_type": "image",
  "matched_segments": []
}

{
  "match": true,
  "confidence": "high",
  "similarity_score": 0.88,
  "processing_time_ms": 1840,
  "media_type": "video",
  "matched_segments": [
    { "source_start": 0.0, "source_end": 12.4, "target_start": 3.2, "target_end": 15.6, "score": 0.91 }
  ]
}

{
  "match": true,
  "confidence": "medium",
  "similarity_score": 0.74,
  "processing_time_ms": 612,
  "media_type": "audio",
  "matched_segments": [
    { "source_start": 5.1, "source_end": 18.9, "target_start": 0.0, "target_end": 13.8, "score": 0.78 }
  ]
}

• match — boolean. Decision based on a sensible per-medium threshold.
• confidence — low / medium / high.
• similarity_score — float in [0, 1]. Use this for custom thresholding.
• processing_time_ms — server-side processing time, integer.
• media_type — image / video / audio.
• matched_segments — array of aligned segments (video / audio); empty for images.

Errors return a non-2xx status code and a JSON body with a stable error.code string and a human-readable error.message.

{
  "error": {
    "code": "invalid_url",
    "message": "source_url is not a reachable http(s) URL"
  }
}

• invalid_url — URL is malformed, not http/https, or points at a private/loopback address.
• fetch_failed — the source or target URL could not be downloaded within the time limit.
• file_too_large — asset exceeds the per-medium size cap.
• duration_too_long — audio or video exceeds the per-medium duration cap.
• unsupported_media — file type is not supported for the called endpoint.
• rate_limited — your RapidAPI plan quota is exhausted.

Synchronous example with requests:

import requests

url = "https://medialayer-image-audio-video-matching-api.p.rapidapi.com/image/match"

payload = {
    "source_url": "https://example.com/a.jpg",
    "target_url": "https://example.com/b.jpg",
}
headers = {
    "x-rapidapi-key": "YOUR_RAPIDAPI_KEY",
    "x-rapidapi-host": "medialayer-image-audio-video-matching-api.p.rapidapi.com",
    "Content-Type": "application/json",
}

response = requests.post(url, json=payload, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

Async example with httpx:

import httpx

async def match_image(source_url: str, target_url: str) -> dict:
    headers = {
        "x-rapidapi-key": "YOUR_RAPIDAPI_KEY",
        "x-rapidapi-host": "medialayer-image-audio-video-matching-api.p.rapidapi.com",
        "Content-Type": "application/json",
    }
    payload = {"source_url": source_url, "target_url": target_url}

    async with httpx.AsyncClient(timeout=30) as client:
        r = await client.post(
            "https://medialayer-image-audio-video-matching-api.p.rapidapi.com/image/match",
            json=payload,
            headers=headers,
        )
        r.raise_for_status()
        return r.json()

Native fetch (Node 18+):

// Node 18+ — global fetch is available, no dependency required.

const res = await fetch(
  "https://medialayer-image-audio-video-matching-api.p.rapidapi.com/image/match",
  {
    method: "POST",
    headers: {
      "x-rapidapi-key": "YOUR_RAPIDAPI_KEY",
      "x-rapidapi-host": "medialayer-image-audio-video-matching-api.p.rapidapi.com",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      source_url: "https://example.com/a.jpg",
      target_url: "https://example.com/b.jpg",
    }),
  },
);

if (!res.ok) {
  throw new Error(`MediaLayer API error: ${res.status}`);
}

const data = await res.json();
console.log(data);

With axios:

import axios from "axios";

const { data } = await axios.post(
  "https://medialayer-image-audio-video-matching-api.p.rapidapi.com/video/match",
  {
    source_url: "https://example.com/a.mp4",
    target_url: "https://example.com/b.mp4",
  },
  {
    headers: {
      "x-rapidapi-key": "YOUR_RAPIDAPI_KEY",
      "x-rapidapi-host": "medialayer-image-audio-video-matching-api.p.rapidapi.com",
      "Content-Type": "application/json",
    },
    timeout: 30_000,
  },
);

console.log(data);

• Use publicly reachable http/https URLs. Private, loopback, link-local, and cloud metadata addresses are rejected by URL validation.
• Stay within the per-medium caps: image 15 MB, audio 50 MB / 300 s, video 100 MB / 180 s.
• Use similarity_score for fine-grained thresholding; match uses a sensible default cutoff per medium.
• Keep your RapidAPI key server-side. Proxy from your backend rather than embedding it in browser or mobile clients.
• For sustained heavy workloads, ingestion pipelines, or VPC deployment, contact MediaLayer AI Labs for enterprise direct API access.

Skip the setup and call the API from your browser using the in-site playgrounds. They proxy through a rate-limited demo route — production traffic should use your RapidAPI key.

• Image playground/playground/image
• Video playground/playground/video
• Audio playground/playground/audio

Or open the MediaLayer listing on RapidAPI to subscribe and copy your key.