Connect Originl to your tools or your AI assistant

What it's for

Who it's for

What you can see and do

Each key has read or read and write permissions and acts with the team role of whoever created it. It only sees your account's profiles.

How it's billed

Included in the Viral plan ($299 a month): 300 variants a month and 4,000 AI credits with the included profile, and up to 10 people on the team.

• The API and MCP have no separate price and no per-request fees.
• Every variant you create and every AI credit you spend counts against your plan, exactly as if you did it in the dashboard. Reading data, approving or scheduling costs nothing.
• Before spending AI credits you request a quote: it tells you what each model will cost and whether your balance covers it. When creating, you state the most you accept to spend; if the price went up, nothing is spent and you are told.
• If you run out of balance, the API returns a clear error and never leaves anything half done.

See the plans

Quickstart in 5 minutes

The examples use curl. Keep your key in an environment variable and never put it in a website's or an app's code: the API does not accept calls from the browser, only from your server.

1. 1

   Create a key

   In the dashboard, Settings, API and MCP. Give it a name (for example, "My server") and choose its permissions. The key starts with ol_live_ and is shown only once.

   bashCopy

   export ORIGINL_API_KEY="ol_live_..."

2. 2

   Check it works

   Returns your account, your plan and the key's permissions.

   bashCopy

   curl https://api.getoriginl.com/v1/cuenta \
     -H "Authorization: Bearer $ORIGINL_API_KEY"

3. 3

   List your profiles

   Note the id of the profile you will work with. Lists are paginated with next_cursor.

   bashCopy

   curl "https://api.getoriginl.com/v1/perfiles?limite=25" \
     -H "Authorization: Bearer $ORIGINL_API_KEY"

4. 4

   Pick a winning video

   Look at its winning videos and pick one as base video by sending its url. Picking costs nothing.

   bashCopy

   curl https://api.getoriginl.com/v1/perfiles/PERFIL_ID/ganadores \
     -H "Authorization: Bearer $ORIGINL_API_KEY"
   
   curl -X POST https://api.getoriginl.com/v1/perfiles/PERFIL_ID/videos \
     -H "Authorization: Bearer $ORIGINL_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{"url": "https://www.instagram.com/reel/C9xYz12AbCd/"}'

5. 5

   Create variants

   Always send an Idempotency-Key: if the connection drops and you retry, you will not get two batches. The result shows up in GET /v1/videos/{id} and in the variante.lista webhook.

   bashCopy

   curl -X POST https://api.getoriginl.com/v1/videos/VIDEO_ID/variantes \
     -H "Authorization: Bearer $ORIGINL_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: 4f7d2c1a-9b8e-4c3d-a2b1-0e9f8d7c6b5a" \
     -d '{"n": "max"}'
   
   curl https://api.getoriginl.com/v1/videos/VIDEO_ID \
     -H "Authorization: Bearer $ORIGINL_API_KEY"

6. 6

   Approve the ones you like

   A copy that is too close to the original cannot be approved: that is how we protect the account.

   bashCopy

   curl -X POST https://api.getoriginl.com/v1/variantes/VARIANTE_ID/aprobar \
     -H "Authorization: Bearer $ORIGINL_API_KEY" \
     -H "Idempotency-Key: $(uuidgen)"

7. 7

   Schedule them

   Pick the time or let the autopilot do it. If it breaks a rule (for example, two variants of the same video less than 72 h apart), you get a 409 with the rule and the nearest valid slot.

   bashCopy

   curl -X POST https://api.getoriginl.com/v1/calendario/VARIANTE_ID/programar \
     -H "Authorization: Bearer $ORIGINL_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{"programada_para": "2026-11-03T18:30:00+01:00"}'
   
   curl "https://api.getoriginl.com/v1/calendario?perfil_id=PERFIL_ID" \
     -H "Authorization: Bearer $ORIGINL_API_KEY"

8. 8

   Measure the results

   Average 72 hour views per month, the change against last month and the best variant. Each variant's metrics are in GET /v1/variantes.

   bashCopy

   curl "https://api.getoriginl.com/v1/perfiles/PERFIL_ID/resultados?meses=2" \
     -H "Authorization: Bearer $ORIGINL_API_KEY"

curl -X POST https://api.getoriginl.com/v1/videos/VIDEO_ID/ia/cotizacion \
  -H "Authorization: Bearer $ORIGINL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"n": 2, "calidad": "estandar"}'
# -> "modelos": [{"modelo": "seedance-2.0-mini", "total": 608, "alcanza": true, ...}]

curl -X POST https://api.getoriginl.com/v1/videos/VIDEO_ID/ia/variantes \
  -H "Authorization: Bearer $ORIGINL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"n": 2, "calidad": "estandar", "modelo": "seedance-2.0-mini", "max_creditos_ia": 608}'

Your AI assistant, connected (MCP)

MCP is the standard AI assistants use to work with external tools. Originl offers a remote MCP server with 18 tools (status, profiles, autopilot, videos, variants, calendar, results, Radar ideas and creating variants) using the same key as the API. With a read-only key, your assistant only sees the read tools.

MCP server URL: https://api.getoriginl.com/mcp

To create with AI, the assistant shows you the quote first and only spends if you accept it.

{
  "mcpServers": {
    "originl": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.getoriginl.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer ol_live_..."
      }
    }
  }
}

claude mcp add --transport http --scope user originl https://api.getoriginl.com/mcp \
  --header "Authorization: Bearer ol_live_..."

{
  "mcpServers": {
    "originl": {
      "type": "http",
      "url": "https://api.getoriginl.com/mcp",
      "headers": {
        "Authorization": "Bearer ${ORIGINL_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "originl": {
      "url": "https://api.getoriginl.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ORIGINL_API_KEY}"
      }
    }
  }
}

Webhooks

Create up to 5 endpoints in Settings, API and MCP. Your server receives a JSON POST each time something happens; the "Send test" button sends a prueba event right away.

What you receive

Headers Originl-Event (the event), Originl-Delivery (delivery id: store it so you never process the same one twice) and Originl-Signature.

POST /tu-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Originl-Webhooks/1.0
Originl-Event: variante.lista
Originl-Delivery: 8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f
Originl-Signature: t=1793112000,v1=5d41402abc4b2a76b9719d911017c592...

{
  "id": "evt_3f9a1c2b7d4e4f60a1b2c3d4e5f60718",
  "type": "variante.lista",
  "created_at": "2026-10-27T18:40:00+00:00",
  "data": {
    "perfil_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
    "video_id": "7d9e1a2b-3c4d-4e5f-8a6b-9c0d1e2f3a4b",
    "variante": { "id": "0b6c3f2e-...", "estado": "propuesta", "calidad": 86.5, "...": "..." }
  }
}

Verify the signature

Originl-Signature looks like t=<seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of the text "t.body" (the raw body, exactly as received) using the whsec_ secret you see only once when creating the endpoint. Reject signatures that do not match and those older than 5 minutes.

import crypto from "node:crypto";

// cuerpo: el cuerpo CRUDO tal cual llega (string), antes de parsear el JSON.
export function firmaValida(cuerpo, cabecera, secreto) {
  const p = Object.fromEntries(cabecera.split(",").map((x) => x.split("=")));
  const esperada = crypto.createHmac("sha256", secreto).update(`${p.t}.${cuerpo}`).digest("hex");
  const a = Buffer.from(esperada), b = Buffer.from(p.v1 ?? "");
  const reciente = Math.abs(Date.now() / 1000 - Number(p.t)) < 300;
  return reciente && a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hashlib, hmac, time

def firma_valida(cuerpo: bytes, cabecera: str, secreto: str) -> bool:
    p = dict(x.split("=", 1) for x in cabecera.split(","))
    esperada = hmac.new(secreto.encode(), f"{p['t']}.".encode() + cuerpo, hashlib.sha256).hexdigest()
    reciente = abs(time.time() - int(p["t"])) < 300
    return reciente and hmac.compare_digest(esperada, p.get("v1", ""))

Retries and delivery

• Reply with a 2xx in under 15 seconds; do the heavy work afterwards.
• If it fails, it is retried after 1, 5 and 30 minutes and after 2, 6 and 12 hours (7 attempts). Each attempt is signed again.
• After 20 failed deliveries in a row the endpoint is disabled and the dashboard says so; you reactivate it with one click.
• Only https (ports 443 or 8443), to public addresses, without following redirects.

Limits

• 60 requests per minute per key and 120 per account. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; over the limit you get a 429 with Retry-After.
• Up to 10 active keys per account. Revoke the ones you do not use.
• Bodies of 64 KB at most. Lists of 1 to 100 items per page (25 by default).
• An Idempotency-Key lasts 24 hours: the same key with the same request returns the same response without repeating the action.
• The calendar is queried in windows of 62 days at most.
• Several wrong keys in a row from the same IP block that IP for a while.

Errors

Always with the right HTTP status and the same shape: {"error": {"code": "...", "message": "..."}}. message is plain language you can show your user (in Spanish for now); branch on code.

HTTP/1.1 409 Conflict
{
  "error": {
    "code": "regla",
    "message": "Hay otra variante del mismo vídeo a menos de 72 horas.",
    "reglas": [{ "codigo": "misma_base", "mensaje": "Hay otra variante del mismo vídeo a menos de 72 horas." }],
    "propuesta": "2026-11-05T17:30:00+00:00"
  }
}

Reference and help