# InfinityLooper API

> Search thousands of free looping video backgrounds and download the MP4s from scripts, apps and AI agents. Search needs no key; downloads need a free API key and share your account's allowance.

- Base URL: `https://infinitylooper.com/api/v1`, JSON answers, RFC 9457 errors.
- MCP server: `https://infinitylooper.com/mcp` for Claude, ChatGPT, Claude Code, Cursor and other MCP apps. Sign in with Google when you connect.
- For machines: [OpenAPI 3.1 spec](https://infinitylooper.com/openapi.json), [this guide in Markdown](https://infinitylooper.com/developers.md), [agent skill](https://infinitylooper.com/skills/infinitylooper/SKILL.md), [llms.txt](https://infinitylooper.com/llms.txt).

## Use it with an AI agent

Give your agent this prompt. It is all the agent needs to find and download loops:

```text
Use the InfinityLooper API to find and download free looping video backgrounds. Read https://infinitylooper.com/developers.md first. My API key is in the INFINITYLOOPER_API_KEY environment variable. Never print the key. If the variable is not set, search without it and ask me to create a key at https://infinitylooper.com/account#api-keys.
```

> **Tip:** Without a key an agent can still search and send people to each loop's page, where they can watch a preview and download it themselves.

## MCP server

Add InfinityLooper to your AI app and ask for loops in plain words. The server is `https://infinitylooper.com/mcp`. When you connect, your app opens a Google sign-in; after you choose Allow it can search and download loops with your account. Downloads use the same allowance as the website.

```text tab="Claude"
In Claude, open Settings, then Connectors, and choose Add custom connector.

Name: InfinityLooper
URL: https://infinitylooper.com/mcp

Choose Connect, sign in with Google and choose Allow.
```

```text tab="ChatGPT"
In ChatGPT, turn on developer mode (Settings, Apps and Connectors, Advanced), then create a connector.

Name: InfinityLooper
MCP server URL: https://infinitylooper.com/mcp
Authentication: OAuth

Sign in with Google and choose Allow.
```

```bash tab="Claude Code"
claude mcp add --transport http infinitylooper https://infinitylooper.com/mcp
# then run /mcp in Claude Code, choose infinitylooper and sign in
```

```json tab="Cursor"
{
  "mcpServers": {
    "infinitylooper": { "url": "https://infinitylooper.com/mcp" }
  }
}
```

```toml tab="Codex (API key)"
# ~/.codex/config.toml
[mcp_servers.infinitylooper]
url = "https://infinitylooper.com/mcp"
bearer_token_env_var = "INFINITYLOOPER_API_KEY"
```

> **Tip:** For scripts and servers with no browser, send an API key instead of signing in: add the header `Authorization: Bearer <your API key>`. The tools are `search_loops`, `get_loop`, `list_themes`, `check_downloads` and `get_download_link`. File links work for 10 minutes, so fetch them straight away.

## Quickstart

### 1. Search, no key needed

```bash
curl "https://infinitylooper.com/api/v1/loops?q=fireplace&orientation=landscape&limit=3"
```

Every result has a `slug`, a page `url`, a `preview_url` you can show, and the file details.

### 2. Get an API key

Sign in with Google at https://infinitylooper.com/account#api-keys and choose Create key. The key is shown once, so put it straight into an environment variable:

```bash
export INFINITYLOOPER_API_KEY="il_live_..."
```

### 3. Download

```bash tab="curl"
curl -s -X POST "https://infinitylooper.com/api/v1/loops/fox-sleeping-by-a-snowy-fireplace/download" \
  -H "Authorization: Bearer $INFINITYLOOPER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  | jq -r '.files[0].url' \
  | xargs curl -L -o fox-sleeping-by-a-snowy-fireplace.mp4
```

```python tab="Python"
import os, uuid, requests

API = "https://infinitylooper.com/api/v1"
KEY = os.environ["INFINITYLOOPER_API_KEY"]

loops = requests.get(f"{API}/loops", params={"q": "rain window", "min_height": 1080, "limit": 1}).json()["data"]
r = requests.post(f"{API}/loops/{loops[0]['slug']}/download",
                  headers={"Authorization": f"Bearer {KEY}", "Idempotency-Key": str(uuid.uuid4())})
r.raise_for_status()
for f in r.json()["files"]:
    with requests.get(f["url"], stream=True) as video, open(f["name"], "wb") as out:
        video.raise_for_status()
        for chunk in video.iter_content(1 << 20):
            out.write(chunk)
    print("saved", f["name"])
```

```javascript tab="JavaScript"
import { writeFile } from "node:fs/promises";

const API = "https://infinitylooper.com/api/v1";
const key = process.env.INFINITYLOOPER_API_KEY;

const { data } = await (await fetch(`${API}/loops?q=rain+window&min_height=1080&limit=1`)).json();
const res = await fetch(`${API}/loops/${data[0].slug}/download`, {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Idempotency-Key": crypto.randomUUID() },
});
if (!res.ok) throw new Error((await res.json()).detail);
for (const f of (await res.json()).files) {
  const video = await fetch(f.url);
  await writeFile(f.name, Buffer.from(await video.arrayBuffer()));
  console.log("saved", f.name);
}
```

The answer has a link for each file that works for 10 minutes. Fetch the files straight away, from your script or server.

> **Note:** File links cannot be fetched by JavaScript running in a web page, because the storage does not allow cross-origin reads. Download from a script or server, or open the link in the browser so it saves the file.

## Connect to Claude

Give Claude two tools: one to search and one to download. The Anthropic Python SDK runs the tool loop for you.

```python tab="Claude API"
import os, uuid, requests
import anthropic
from anthropic import beta_tool

API = "https://infinitylooper.com/api/v1"
KEY = os.environ["INFINITYLOOPER_API_KEY"]

@beta_tool
def search_loops(query: str, orientation: str = "", min_height: int = 0) -> str:
    """Search InfinityLooper's free looping video backgrounds.

    Args:
        query: Search words, for example "rain window" or "space".
        orientation: "landscape", "vertical" or "" for any.
        min_height: Smallest frame height in pixels, 1080 for Full HD or 2160 for 4K. 0 for any.
    """
    params = {"q": query, "limit": 5}
    if orientation:
        params["orientation"] = orientation
    if min_height:
        params["min_height"] = min_height
    return requests.get(f"{API}/loops", params=params).text

@beta_tool
def download_loop(slug: str) -> str:
    """Download a loop's MP4 into the current folder and return the saved file names.

    Args:
        slug: The loop's slug from search_loops.
    """
    r = requests.post(f"{API}/loops/{slug}/download",
                      headers={"Authorization": f"Bearer {KEY}", "Idempotency-Key": str(uuid.uuid4())})
    if not r.ok:
        return r.text
    names = []
    for f in r.json()["files"]:
        with open(f["name"], "wb") as out:
            out.write(requests.get(f["url"]).content)
        names.append(f["name"])
    return "Saved " + ", ".join(names)

client = anthropic.Anthropic()
runner = client.beta.messages.tool_runner(
    model="claude-opus-5-5",
    max_tokens=16000,
    betas=["server-side-fallback-2026-07-01"],
    fallbacks="default",
    tools=[search_loops, download_loop],
    messages=[{"role": "user", "content": "Find a calm rainy window loop in 1080p and download it."}],
)
for message in runner:
    for block in message.content:
        if block.type == "text":
            print(block.text)
```

```text tab="Claude Code"
Install the InfinityLooper skill, then ask for loops in plain words:

mkdir -p ~/.claude/skills/infinitylooper
curl -o ~/.claude/skills/infinitylooper/SKILL.md https://infinitylooper.com/skills/infinitylooper/SKILL.md
```

```text tab="Claude app"
Open Claude at https://claude.ai and paste the agent prompt from "Use it with an AI agent". With a web tool Claude reads this guide, searches the catalogue and links you to each loop's page to download.
```

## Connect to OpenAI

Use function calling in the Responses API. The two functions are the same as in the Claude example: `search_loops` and `download_loop`.

```python tab="OpenAI API"
import json
from openai import OpenAI

# search_loops and download_loop: the same functions as in the Claude example, without the @beta_tool line.
TOOLS = [
    {"type": "function", "name": "search_loops",
     "description": "Search InfinityLooper's free looping video backgrounds.",
     "parameters": {"type": "object", "properties": {
         "query": {"type": "string", "description": "Search words, for example rain window or space."},
         "orientation": {"type": "string", "enum": ["", "landscape", "vertical"]},
         "min_height": {"type": "integer", "description": "1080 for Full HD, 2160 for 4K, 0 for any."}},
         "required": ["query"]}},
    {"type": "function", "name": "download_loop",
     "description": "Download a loop's MP4 into the current folder.",
     "parameters": {"type": "object", "properties": {"slug": {"type": "string"}}, "required": ["slug"]}},
]
FUNCTIONS = {"search_loops": search_loops, "download_loop": download_loop}

client = OpenAI()
items = [{"role": "user", "content": "Find a calm rainy window loop in 1080p and download it."}]
while True:
    response = client.responses.create(model="gpt-5", tools=TOOLS, input=items)
    calls = [o for o in response.output if o.type == "function_call"]
    if not calls:
        print(response.output_text)
        break
    items += response.output
    for call in calls:
        result = FUNCTIONS[call.name](**json.loads(call.arguments))
        items.append({"type": "function_call_output", "call_id": call.call_id, "output": result})
```

```text tab="ChatGPT GPT"
In ChatGPT, create a GPT and open Configure, then Actions:

1. Choose Import from URL and enter https://infinitylooper.com/openapi.json
2. Authentication: API key, Auth type Bearer, and paste your InfinityLooper key.
3. Privacy policy: https://infinitylooper.com/privacy

The GPT can then search, check downloads left and fetch download links.
```

```text tab="ChatGPT app"
Open ChatGPT at https://chatgpt.com and paste the agent prompt from "Use it with an AI agent". ChatGPT reads this guide, searches the catalogue and links you to each loop's page to download.
```

> **Note:** Keep your key in an environment variable or your platform's secret store. Never paste it into a chat.

## Agent skill

The skill teaches coding agents such as Claude Code, Codex and Cursor how to use this API: when to search, how to download, and how to handle errors and downloads left.

```bash
mkdir -p ~/.claude/skills/infinitylooper
curl -o ~/.claude/skills/infinitylooper/SKILL.md https://infinitylooper.com/skills/infinitylooper/SKILL.md
```

Other agents can read the same file from https://infinitylooper.com/skills/infinitylooper/SKILL.md or from this guide.

## Authentication

Send your key in the Authorization header:

```http
Authorization: Bearer il_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Search, loop details and themes need no key; downloads and `/me` do. A key spends the downloads of the Google account that created it. Create and revoke keys at https://infinitylooper.com/account#api-keys; a revoked key stops at once. Keys start with `il_live_` so secret scanners can spot a leak, and carry the `read` and `download` scopes.

> **Warning:** Keep keys out of web pages, apps you ship and public repositories. Anyone with the key can spend your downloads.

## Endpoints

### Search loops

`GET /loops`

| Parameter | Type | Default | Description |
|---|---|---|---|
| `q` | string |  | Search words, ranked like the search box on the site. Spelling variants (cosy, cozy), synonyms (galaxy, space), plurals and typos are understood. |
| `theme` | string |  | A theme id from `GET /themes`, for example `rain` or `fireplace`. |
| `orientation` | string |  | `landscape` or `vertical`. |
| `min_height` | integer |  | Smallest frame height in pixels. For landscape loops `1080` is Full HD and `2160` is 4K. Vertical loops are taller than they are wide. |
| `has_audio` | boolean |  | `true` or `false`. Most loops are silent. |
| `max_duration` | number |  | Longest loop length in seconds, inclusive. |
| `limit` | integer | `20` | Results per page, 1 to 100. |
| `cursor` | string |  | `next_cursor` from the previous page. |

```bash
curl "https://infinitylooper.com/api/v1/loops?theme=fireplace&limit=1"
```

```json
{
  "data": [
    {
      "id": "IL-AB-0016",
      "slug": "fox-sleeping-by-a-snowy-fireplace",
      "title": "Fox sleeping by a snowy fireplace animated background",
      "url": "https://infinitylooper.com/free/animated-backgrounds/fox-sleeping-by-a-snowy-fireplace",
      "description": "A fox sleeps beside a fireplace with snow-covered trees outside. A silent 10-second 1080p loop, 3.6 MB.",
      "best_for": ["TV ambience", "Stream scene in OBS or Streamlabs"],
      "tags": ["fox", "fireplace", "snow", "winter"],
      "themes": ["snow", "fireplace", "cute-animals"],
      "preview_url": "https://infinitylooper.com/previews/v4/IL-AB-0016.mp4",
      "poster_url": "https://infinitylooper.com/free/posters/hd/IL-AB-0016-640.webp",
      "file": {
        "width": 1916,
        "height": 1080,
        "resolution": "1916 x 1080 (1080p Full HD)",
        "orientation": "landscape",
        "duration_seconds": 10.041667,
        "format": "MP4 (H.264)",
        "has_audio": false,
        "size": "3.6 MB"
      },
      "licence": { "type": "standard", "credit": null, "source_url": null, "url": "https://infinitylooper.com/terms#licence" }
    }
  ],
  "next_cursor": "eyJvIjoxfQ",
  "total": 499
}
```

Pass `next_cursor` back as `cursor` to get the next page. It is `null` on the last page. Counts in these examples change as the library grows.

When you send `q`, the answer also has a `search` object that says how the words were read:

```json
{ "search": { "query": "cozy rain window", "words": ["cosy", "rain", "window"], "dropped": [], "relaxed": [], "corrected_to": null } }
```

A word that no loop matches together with the others is set aside and listed in `dropped`, so you still get the closest loops. When nothing matches at all, `data` is empty and every word is in `dropped`.

> **Tip:** Short queries work best: one to three words such as "rain window" or "space". Use `theme`, `orientation` and `min_height` to narrow down.

### Get a loop

`GET /loops/{slug}`

Takes the slug or the id (`IL-AB-0016`). Returns one loop in the same shape as a search result.

```bash
curl "https://infinitylooper.com/api/v1/loops/fox-sleeping-by-a-snowy-fireplace"
```

### List themes

`GET /themes`

```bash
curl "https://infinitylooper.com/api/v1/themes"
```

```json
{
  "data": [
    { "id": "rain", "name": "Rain", "url": "https://infinitylooper.com/free/theme/rain", "count": 331 },
    { "id": "snow", "name": "Snow and winter", "url": "https://infinitylooper.com/free/theme/snow", "count": 289 }
  ],
  "total": 23
}
```

### Download a loop

`POST /loops/{slug}/download`

| Header | Required | Description |
|---|---|---|
| `Authorization` | yes | `Bearer <your API key>` |
| `Idempotency-Key` | no | Any unique string, 1 to 128 visible characters. A retry with the same value is never counted twice. |

```bash
curl -X POST "https://infinitylooper.com/api/v1/loops/fox-sleeping-by-a-snowy-fireplace/download" \
  -H "Authorization: Bearer $INFINITYLOOPER_API_KEY" \
  -H "Idempotency-Key: 6f1c2b8e-3d47-4b0a-9a51-2e8f0c7d9b14"
```

```json
{
  "loop": {
    "id": "IL-AB-0016",
    "slug": "fox-sleeping-by-a-snowy-fireplace",
    "title": "Fox sleeping by a snowy fireplace animated background",
    "url": "https://infinitylooper.com/free/animated-backgrounds/fox-sleeping-by-a-snowy-fireplace",
    "licence": { "type": "standard", "credit": null, "source_url": null, "url": "https://infinitylooper.com/terms#licence" }
  },
  "files": [
    {
      "name": "fox-sleeping-by-a-snowy-fireplace.mp4",
      "bytes": 3751747,
      "variant": null,
      "url": "<signed link to the file, valid for 10 minutes>",
      "expires_at": "2026-11-17T09:10:00.000Z"
    }
  ],
  "redownload": false,
  "counted": true
}
```

The answer also has a `usage` object with your account's numbers, the same as `GET /me`:

| Field | Type | Description |
|---|---|---|
| `plan` | string | `free` or `max`. |
| `limit` | integer | Downloads allowed in the rolling window. |
| `used` | integer | Downloads counted in the window. |
| `remaining` | integer | Downloads left. |
| `resets_at` | string or null | When the oldest counted download leaves the window. `null` while there is room. |
| `window_days` | integer | Length of the rolling window, 30. |

`redownload` is `true`, and nothing is counted, when the account already downloaded this loop in the last 30 days. Some loops have more than one file, such as a vertical cut: `variant` names it.

### Check your downloads

`GET /me`

```bash
curl "https://infinitylooper.com/api/v1/me" -H "Authorization: Bearer $INFINITYLOOPER_API_KEY"
```

Returns the `usage` fields above, plus `key` with its `id` and `scopes`. Call it before a batch of downloads.

## Downloads and rate limits

- **Downloads:** scripts and agents are welcome to download in bulk, within the account's downloads. Your keys and the website share one download allowance per account over a rolling 30 days. A loop the account already downloaded in that time is free to download again. Check `GET /me`, or read these headers on every keyed answer:

```http
RateLimit-Policy: "downloads";q=<allowance>;w=2592000
RateLimit: "downloads";r=<remaining>;t=<seconds until one frees up>
```

- **Requests:** up to 120 requests a minute from one address, and 30 a minute per key. Over the address limit the edge answers `429` in plain text: wait a minute. Over the key limit you get a `rate-limited` problem with `Retry-After` in seconds.
- **File links** work for 10 minutes (`expires_at`). Ask for new ones with the same call. A re-download of the same loop is free.
- Search answers may be cached for up to five minutes.

## Errors

Every error has `type`, `title`, `status` and `detail`. Switch on `type`, which ends in one of these:

| Status | type | What to do |
|---|---|---|
| 400 | `invalid-parameter` | A parameter is unknown or not valid, or the Idempotency-Key header is not valid. The `parameter` field names it. |
| 401 | `unauthorized` | No key was sent. Add `Authorization: Bearer <your key>`. |
| 401 | `invalid-key` | The key is wrong or revoked. Create a new one on your account page. |
| 403 | `insufficient-scope` | The key does not have permission for this endpoint. |
| 404 | `not-found` | No published loop has this slug or id, or the path does not exist. |
| 405 | `method-not-allowed` | Wrong HTTP method. Downloads are POST, everything else is GET. |
| 429 | `free-limit` | The account has used its downloads for now. `resets_at` and `Retry-After` say when the next one is available. Loops it already downloaded stay free. The `premium` field says Premium Access, for people who need more downloads, is being built. |
| 429 | `rate-limited` | Too many requests with this key. Wait for `Retry-After` seconds. Too many from one address gets a plain-text `429` from the edge instead: wait a minute. |
| 503 | `unavailable` | A service the API needs is down. Nothing was charged. Retry after `Retry-After`. |
| 500 | `server-error` | Something went wrong on our side. Try again. |

```json
{
  "type": "https://infinitylooper.com/developers#errors-invalid-key",
  "title": "Invalid API key",
  "status": 401,
  "detail": "This API key is not valid or has been revoked. Create a new one on your account page."
}
```

## Licence and credit

Every loop names its licence, and the download answer repeats it. The licence at https://infinitylooper.com/terms#licence covers personal, commercial and client work, including monetised videos and streams. Public domain loops name their source in `licence.source_url`. When `licence.credit` is set, show that credit.

## Support

Questions and key problems go through the support form at https://infinitylooper.com/help?request=1#contact.
