Getting started

The ShortFast API creates short-form videos from a brief, edits everything the pipeline produced, renders them to mp4, publishes them to your connected social accounts, runs them on a schedule with automations, and pushes real-time events to your webhooks.

Base URL

https://app.shortfast.com/api/v1

Create an API key

Create and revoke keys under Settings > API & Webhooks in the ShortFast app. A key's full value is shown only once, at creation, so store it securely. Each key is scoped to the workspace it was created in, and every query the API runs is scoped to that workspace.

Your first request

GET / returns API metadata plus the workspace your key resolved to, so it is the cheapest way to check that a key works:

curl https://app.shortfast.com/api/v1/ \
  -H "Authorization: Bearer sf_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "data": {
    "name": "ShortFast API",
    "version": "v1",
    "docs": "https://developer.shortfast.com",
    "workspace": {
      "id": "k9WmT3xR2pQ7nV4bd",
      "name": "Acme Studio",
      "plan": "pro",
      "credits": { "credits": 42500, "tokens": 42500000 },
      "limits": {
        "maxRendersPerMonth": null,
        "maxAutomations": 3,
        "maxProfiles": 3,
        "maxVideoDurationSeconds": 7200,
        "maxRenderSeconds": 720,
        "storageBytes": 50000000000,
        "watermark": false
      },
      "usage": { "storageBytes": 3187441664, "profiles": 2 }
    }
  }
}

The response envelope

Every response is a JSON object with a data key. List endpoints add a paging object and accept limit (1 to 100, default 50) and offset query parameters:

{
  "data": [],
  "paging": { "limit": 50, "offset": 0, "total": 128 }
}

Single-resource endpoints return the same envelope without paging. Two lists are deliberately unpaginated because they are small and static: /profiles and everything under /reference.

Errors

Errors use standard HTTP status codes with a JSON body:

{
  "error": {
    "status": 409,
    "code": "warning-publish-not-configured",
    "message": "No profile selected"
  }
}

code is the stable, machine-readable identifier to branch on. The message wording may change over time; the code will not. details is present only when an error carries structured context, and code is absent on plain validation errors.

The codes you will branch on most:

Plan ceilings and job failures share one vocabulary (warning-plan-renders, warning-publish-auth, and the rest). The same code appears on a synchronous 400 and on a failed job's process.error.code / render.error.code / publish.error.code, and the whole list is readable at GET /reference/failure-codes. See Credits and limits.

Retrying safely

Every POST that queues real work or charges credits accepts an optional header:

Idempotency-Key: 4f1c9e2a-6b81-4f0d-9a3e-2c5d7e8b1a44

The first request with a given key runs the action and stores its response. A retry with the same key replays that stored response byte for byte instead of generating, rendering, publishing or charging a second time, so a client timeout is safe to retry. Keys are scoped per workspace and per target, so the same key can never cross two videos or two endpoints. With no header the action simply runs.

Reference