Splicora for scripts and agents

The same operations the app performs, through the same services: create a project from a link, find the clips in it, generate media, publish and schedule. Over HTTP, or as tools in any MCP client.

For what the API is for and what it costs, read the overview.

Get a key

Make one in Settings, then API keys, once you are signed in. It is shown once and stored as a hash, so copy it when you make it. A key acts on the workspace it was made in and spends that workspace's credits; revoking it is immediate.

curl https://splicora.ai/api/v1/library \
  -H "Authorization: Bearer splk_your_key_here"

How the long operations work

Anything that takes more than a moment answers with a job rather than holding the request open. The credits are reserved and the job row exists by the time you get the answer, so a job id always means the work is under way. Poll GET /api/v1/jobs/{id} until done is true, then read succeeded. A job that failed has already been refunded in full.

Errors

Every failure is JSON: error is a sentence, code is a stable identifier, and details.fields names each offending argument when the problem was the arguments: that one is a 422, because the request parsed and it is its content that cannot be acted on. A 401 means the key is missing, wrong or revoked; the three answer the same on purpose. A 429 carries Retry-After in seconds.

The operations

POST /api/v1/projects MCP: create_project

Create a project from a URL

Takes a link to a video or a podcast episode -- YouTube, Vimeo, Drive, Dropbox, or a direct URL to a media file you have uploaded somewhere -- and creates a project from it. Nothing is generated and nothing is charged until you ask for it, so this is safe to call before deciding what to make.

  • urlstringrequired
    A link to the video or audio. Also accepts a direct URL to a media file.
  • wantsobject
    What to make from the project. Everything is optional; nothing is made until you ask.
  • templatestring
    A preset bundle of wants, by id. Overridden by `wants` when both are given.
GET /api/v1/projects/{id} MCP: get_project

Read a project

The project, plus what has been made from it so far: its clips and its written pieces. Poll this after starting work, or poll the job it returned.

  • idstringrequired
    The project id.
POST /api/v1/projects/{id}/clips MCP: find_clips

Find the short clips in a project

Reads the transcript and picks the moments worth cutting. Transcribes the source first if that has not happened yet, so this can be the first thing you call on a new project. Charges credits.

  • idstringrequired
    The project id.
  • maxClipsinteger
    How many moments to find. Each one is priced.
POST /api/v1/generate MCP: generate

Generate an image, a video, a voice-over or a track

Starts a generation and answers with a job. The credits are reserved and the job row exists by the time you get the answer, so a job id always means the work is under way. Poll `GET /jobs/{id}` for the result. Prices are per model and are listed at /pricing.

  • kindimage | video | speech | music | soundrequired
    Which catalogue the model belongs to.
  • modelstringrequired
    The model id, as the models catalogue lists it for that kind.
  • inputobjectrequired
    What the model takes: `prompt`, and `seconds` for anything priced by time.
GET /api/v1/jobs/{id} MCP: get_job

Read a job

The status of a piece of background work. Poll until `done` is true, then read `succeeded`. A failed job has already been refunded by the time you see it.

  • idstringrequired
    The job id.
POST /api/v1/publish MCP: publish

Publish to a connected account

Posts immediately to one of the accounts connected to this workspace. The account must already be connected in the browser -- this does not do OAuth.

  • connectionIdstringrequired
    Which connected account to post to.
  • captionstring
  • titlestring
  • descriptionstring
  • mediaUrlstring
    A public URL to the video or image to post.
  • linkstring
    A URL to attach under the post.
  • tagsstring[]
  • privacystring
POST /api/v1/schedule MCP: schedule

Schedule a post for later

Writes a calendar entry and posts it at `runAt`. Nothing reaches the platform now. Same arguments as publish, plus the time.

  • connectionIdstringrequired
  • runAtstringrequired
    When to post, as an ISO 8601 timestamp. Must be in the future.
  • timezonestring
    An IANA zone, so the calendar shows the post at its owner's wall clock.
  • captionstring
  • titlestring
  • descriptionstring
  • mediaUrlstring
  • linkstring
  • tagsstring[]
  • notesstring
GET /api/v1/library MCP: list_library

List everything made in this workspace

The same list the Library page shows: clips, written pieces, visuals and uploads, newest first, with the same filters.

  • typeall | clips | writing | visuals | uploads
    Which kind of item to list.
  • projectstring
    Only items from this project.
  • qstring
    Free-text search.
  • pageinteger
    Which page of results, from 1.
POST /api/v1/webhooks MCP: subscribe

Subscribe to events

Registers a URL we POST a signed JSON body to when something happens, so your system does not have to poll. The response carries the signing secret, and it is the only place you will get it. Deliveries are retried for about four hours if your endpoint does not answer.

  • urlstringrequired
    A public https URL. Private networks and localhost are refused.
  • eventsstring[]required
    Which events to send. Nothing is sent for an event you did not name.
  • namestring
    A label, so you can tell endpoints apart.
DELETE /api/v1/webhooks/{id} MCP: unsubscribe

Stop sending to an endpoint

Removes the subscription and its delivery history. Anything still queued for it is dropped rather than sent.

  • idstringrequired
    The subscription id.

The full document

/api/v1/openapi.json is an OpenAPI 3.1 document generated from the same schemas that validate these requests, so it describes exactly what the API accepts and returns. Point a client generator or an explorer at it.

Webhooks

Rather than polling, have Splicora POST to you. Add an endpoint at Settings, then Webhooks once you are signed in, or call POST /api/v1/webhooks with a URL and the events you want. The response carries the signing secret.

Every delivery carries three headers:

X-Splicora-Signature: t=1800000000,v1=6c07727381477a…
X-Splicora-Event:     clip.ready
X-Splicora-Delivery:  wd_4f2a91c3e8

The signature is HMAC-SHA256 over <timestamp>.<body>, hex, using that endpoint's secret, not over the body alone. Signing the body alone produces a signature that stays valid forever, so anyone who captures one delivery could replay those exact bytes at your endpoint and the check would pass every time. Sign the raw body bytes, before parsing: a body that has been parsed and re-serialised is a different string.

X-Splicora-Delivery is the same on every retry of an event, so use it to be idempotent: the same id twice is one fact, not two.

const crypto = require("crypto");

function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(",").map((pair) => pair.split("=").map((s) => s.trim()))
  );
  const t = Number(parts.t);
  if (!Number.isFinite(t)) return false;
  // Both directions: a delivery from the future is as suspect as a stale one.
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(t + "." + rawBody, "utf8")
    .digest("hex");

  if (parts.v1.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Answer 2xx and we are done. Anything else is retried 8 times over about four and a half hours: after 10 seconds, 30 seconds, 2 minutes, 5 minutes, 15 minutes, 1 hour and 3 hours. A 4xx is retried too, because a framework answering 404 while it boots is common. Redirects are not followed: a 3xx counts as a failed attempt. Every attempt and its response are visible on the Settings page.

MCP

Every operation above is also an MCP tool at https://splicora.ai/mcp, over streamable HTTP, authenticated with the same key. The server is stateless, so each call is one POST: there is no session to open.

{
  "mcpServers": {
    "splicora": {
      "url": "https://splicora.ai/mcp",
      "headers": { "Authorization": "Bearer splk_your_key_here" }
    }
  }
}

We use cookies for analytics. Necessary cookies always run. Cookie Policy