Reference

Beta

Capxion API reference

Generated from the OpenAPI contract (version 1.0.0-beta) that the SDKs and MCP server are built from. Base URL https://api.capxion.me/v1; authenticate with Authorization: Bearer sk_live_….

openapi.yaml

Uploads

Get a signed URL to upload a media file directly to storage

POST/uploads

Reserves an upload slot. Send the bytes straight to storage without your API key, in either of two ways: - **Single PUT** (files up to 6 MB): PUT upload_url with the file's Content-Type. - **Resumable** (recommended above 6 MB, required for large files): the [TUS 1.0.0](https://tus.io/protocols/resumable-upload) protocol against resumable.endpoint. POST it with Tus-Resumable: 1.0.0, Upload-Length: <size>, Upload-Metadata (each resumable.metadata entry as key base64(value), comma-separated) and resumable.headers; then PATCH the returned Location with resumable.chunk_size bytes at a time (Content-Type: application/offset+octet-stream, Upload-Offset, resumable.headers). After a failure, HEAD the Location (with resumable.headers) to read Upload-Offset and continue from there. Any TUS client works (tus-js-client, tuspy, ...); the official SDKs do this automatically. Both ways expire at expires_at; then create a project with upload_id. Slots that no project uses are deleted after 24 h.

Body · object

filenamerequired
stringmax 200 chars
content_typerequired
string
audio/* or video/*
sizerequired
integermin 1
Bytes; checked against the plan's upload limit

Responses

201Upload slot. Send the bytes to upload_url (single PUT) or via resumable (TUS), then create a project with upload_id.object
400ErrorError
401ErrorError
413ErrorError

Requestcurl

curl -X POST "https://api.capxion.me/v1/uploads" \
  -H "Authorization: Bearer $CAPXION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "filename": "studio-session.mp4",
      "content_type": "video/mp4",
      "size": 48211337
    }'

Response 201json

{
  "upload_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "upload_url": "https://<project>.supabase.co/storage/v1/object/upload/sign/media/...",
  "expires_at": "2026-10-10T14:03:22Z",
  "resumable": {
    "endpoint": "https://<project>.supabase.co/storage/v1/upload/resumable/sign",
    "headers": {
      "x-signature": "eyJhbGciOi..."
    },
    "metadata": {
      "bucketName": "media",
      "objectName": "<user_id>/uploads/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/studio-session.mp4",
      "contentType": "video/mp4"
    },
    "chunk_size": 6291456
  }
}

Projects

List projects

GET/projects

Parameters

limitquery
integer1 to 100 · default 20
cursorquery
string
Opaque cursor from next_cursor
statusquery
ProjectStatusimportingdrafttranscribingreadyfailed

Responses

200Newest firstobject
401ErrorError

Requestcurl

curl "https://api.capxion.me/v1/projects" \
  -H "Authorization: Bearer $CAPXION_API_KEY"

Response 200json

{
  "data": [
    {
      "id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
      "title": "Studio session, take 3",
      "status": "importing",
      "kind": "song",
      "source": "audio",
      "language": "en",
      "duration": 184.6,
      "format": "16:9",
      "style": {
        "template": "clean",
        "font": "Inter",
        "font_size": 16,
        "color": "#ffffff",
        "highlight": "#ffd84d",
        "placement": "top",
        "max_lines": 1,
        "readable_lines": true
      },
      "error": null,
      "job_id": "c5d1e9f0-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "created_at": "2026-10-10T14:03:22Z"
    }
  ],
  "next_cursor": "WyIyMDI2LTEwLTEwVDEwOjAwOjAwWiIsIjNmMGMiXQ"
}

Create a project from an uploaded file or a public media URL

POST/projects

Exactly one of upload_id or source_url. A source_url is imported asynchronously (status importing), then transcription starts automatically when auto_transcribe is true. source_url must be a direct HTTPS link to an audio/video file (Dropbox share links are accepted); links to streaming sites are rejected.

Parameters

Idempotency-Keyheader
stringmax 200 chars
Retrying a request with the same key (within 24h) returns the original response instead of doing the work twice.

Body · CreateProject

title
stringmax 200 chars
upload_id
string
source_url
stringuri
kind
ProjectKindsongpodcastspeechvideoaudio
language
stringdefault "auto"
text
string
Optional lyrics/script; improves accuracy
format
Aspect16:99:164:51:1
style
CaptionStyle
auto_transcribe
booleandefault true

Responses

201CreatedProject
400ErrorError
401ErrorError
402ErrorError
422ErrorError

Requestcurl

curl -X POST "https://api.capxion.me/v1/projects" \
  -H "Authorization: Bearer $CAPXION_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
      "title": "Studio session, take 3",
      "source_url": "https://cdn.example.com/media/studio-session.mp4",
      "kind": "song",
      "language": "auto",
      "text": "Every word in its place",
      "format": "16:9",
      "style": {
        "template": "clean",
        "font": "Inter",
        "font_size": 16,
        "color": "#ffffff",
        "highlight": "#ffd84d",
        "placement": "top",
        "max_lines": 1,
        "readable_lines": true
      },
      "auto_transcribe": true
    }'

Response 201json

{
  "id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
  "title": "Studio session, take 3",
  "status": "importing",
  "kind": "song",
  "source": "audio",
  "language": "en",
  "duration": 184.6,
  "format": "16:9",
  "style": {
    "template": "clean",
    "font": "Inter",
    "font_size": 16,
    "color": "#ffffff",
    "highlight": "#ffd84d",
    "placement": "top",
    "max_lines": 1,
    "readable_lines": true
  },
  "error": null,
  "job_id": "c5d1e9f0-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "created_at": "2026-10-10T14:03:22Z"
}

Get project

GET/projects/{project_id}

Parameters

project_idrequiredpath
string

Responses

200OKProject
404ErrorError

Requestcurl

curl "https://api.capxion.me/v1/projects/PROJECT_ID" \
  -H "Authorization: Bearer $CAPXION_API_KEY"

Response 200json

{
  "id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
  "title": "Studio session, take 3",
  "status": "importing",
  "kind": "song",
  "source": "audio",
  "language": "en",
  "duration": 184.6,
  "format": "16:9",
  "style": {
    "template": "clean",
    "font": "Inter",
    "font_size": 16,
    "color": "#ffffff",
    "highlight": "#ffd84d",
    "placement": "top",
    "max_lines": 1,
    "readable_lines": true
  },
  "error": null,
  "job_id": "c5d1e9f0-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "created_at": "2026-10-10T14:03:22Z"
}

Rename or change caption style / format

PATCH/projects/{project_id}

Parameters

project_idrequiredpath
string

Body · object

title
stringmax 200 chars
style
CaptionStyle
format
Aspect16:99:164:51:1

Responses

200OKProject
404ErrorError
409ErrorError

Requestcurl

curl -X PATCH "https://api.capxion.me/v1/projects/PROJECT_ID" \
  -H "Authorization: Bearer $CAPXION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "title": "Studio session, take 3",
      "style": {
        "template": "clean",
        "font": "Inter",
        "font_size": 16,
        "color": "#ffffff",
        "highlight": "#ffd84d",
        "placement": "top",
        "max_lines": 1,
        "readable_lines": true
      },
      "format": "16:9"
    }'

Response 200json

{
  "id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
  "title": "Studio session, take 3",
  "status": "importing",
  "kind": "song",
  "source": "audio",
  "language": "en",
  "duration": 184.6,
  "format": "16:9",
  "style": {
    "template": "clean",
    "font": "Inter",
    "font_size": 16,
    "color": "#ffffff",
    "highlight": "#ffd84d",
    "placement": "top",
    "max_lines": 1,
    "readable_lines": true
  },
  "error": null,
  "job_id": "c5d1e9f0-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "created_at": "2026-10-10T14:03:22Z"
}

Delete project

DELETE/projects/{project_id}

Parameters

project_idrequiredpath
string

Responses

204Deleted
404ErrorError

Requestcurl

curl -X DELETE "https://api.capxion.me/v1/projects/PROJECT_ID" \
  -H "Authorization: Bearer $CAPXION_API_KEY"

Status of an import or transcription job

GET/jobs/{job_id}

Parameters

job_idrequiredpath
string

Responses

200OKJob
404ErrorError

Requestcurl

curl "https://api.capxion.me/v1/jobs/JOB_ID" \
  -H "Authorization: Bearer $CAPXION_API_KEY"

Response 200json

{
  "id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
  "type": "import",
  "project_id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
  "status": "queued",
  "progress": 0.42,
  "error": null
}

Transcripts

Start (or re-run) transcription / alignment

POST/projects/{project_id}/transcribe

Uses the project's text when present (align), otherwise transcribes. Returns a job.

Parameters

project_idrequiredpath
string
Idempotency-Keyheader
stringmax 200 chars
Retrying a request with the same key (within 24h) returns the original response instead of doing the work twice.

Body (optional) · object

language
stringdefault "auto"
ISO 639-1 or 'auto'
text
string
Optional lyrics/script to align against (replaces stored text)

Responses

202QueuedJob
402ErrorError
404ErrorError
409ErrorError

Requestcurl

curl -X POST "https://api.capxion.me/v1/projects/PROJECT_ID/transcribe" \
  -H "Authorization: Bearer $CAPXION_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
      "language": "auto",
      "text": "Every word in its place"
    }'

Response 202json

{
  "id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
  "type": "import",
  "project_id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
  "status": "queued",
  "progress": 0.42,
  "error": null
}

Get transcript

GET/projects/{project_id}/transcript

Parameters

project_idrequiredpath
string
formatquery
enumdefault "json"jsonsrtvtttxt

Responses

200Word-level transcript (json) or a subtitle/text fileTranscriptapplication/json, text/plain, text/vtt, application/x-subrip
404ErrorError
409ErrorError

Requestcurl

curl "https://api.capxion.me/v1/projects/PROJECT_ID/transcript" \
  -H "Authorization: Bearer $CAPXION_API_KEY"

Response 200json

{
  "project_id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
  "language": "en",
  "duration": 184.6,
  "text": "Every word in its place",
  "lines": [
    {
      "words": [
        null
      ]
    }
  ]
}

Replace lines/words (edited text and timing)

PUT/projects/{project_id}/transcript

Parameters

project_idrequiredpath
string

Body · object

linesrequired
Line[]

Responses

200OKTranscript
400ErrorError
404ErrorError

Requestcurl

curl -X PUT "https://api.capxion.me/v1/projects/PROJECT_ID/transcript" \
  -H "Authorization: Bearer $CAPXION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "lines": [
        {
          "words": [
            {
              "text": null,
              "start": null,
              "end": null
            }
          ]
        }
      ]
    }'

Response 200json

{
  "project_id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
  "language": "en",
  "duration": 184.6,
  "text": "Every word in its place",
  "lines": [
    {
      "words": [
        null
      ]
    }
  ]
}

Exports

List exports

GET/projects/{project_id}/exports

Parameters

project_idrequiredpath
string

Responses

200Newest firstobject

Requestcurl

curl "https://api.capxion.me/v1/projects/PROJECT_ID/exports" \
  -H "Authorization: Bearer $CAPXION_API_KEY"

Response 200json

{
  "data": [
    {
      "id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
      "project_id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
      "batch_id": "e4f5a6b7-c8d9-4e0f-9a1b-2c3d4e5f6a7b",
      "preset": "youtube",
      "status": "queued",
      "progress": 0.42,
      "width": 1080,
      "height": 1920,
      "credits": 12,
      "download_url": "https://<project>.supabase.co/storage/v1/object/sign/media/...",
      "error": null,
      "created_at": "2026-10-10T14:03:22Z",
      "completed_at": "2026-10-10T14:03:22Z"
    }
  ]
}

Render the project for one or more platform presets

POST/projects/{project_id}/exports

Parameters

project_idrequiredpath
string
Idempotency-Keyheader
stringmax 200 chars
Retrying a request with the same key (within 24h) returns the original response instead of doing the work twice.

Body · CreateExports

presetsrequired
PresetId[]1 to 6 itemsyoutubeyoutube_shortstiktokinstagram_reelsinstagram_feedlinkedin
resolution
enumdefault "1080p"720p1080p2160p
burn_captions
booleandefault true
range_start
numbermin 0
range_end
numbermin 0

Responses

202One export per preset, sharing a batch_idobject
402ErrorError
403ErrorError
409ErrorError

Requestcurl

curl -X POST "https://api.capxion.me/v1/projects/PROJECT_ID/exports" \
  -H "Authorization: Bearer $CAPXION_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
      "presets": [
        "youtube"
      ],
      "resolution": "1080p",
      "burn_captions": true,
      "range_start": 0,
      "range_end": 0
    }'

Response 202json

{
  "batch_id": "e4f5a6b7-c8d9-4e0f-9a1b-2c3d4e5f6a7b",
  "data": [
    {
      "id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
      "project_id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
      "batch_id": "e4f5a6b7-c8d9-4e0f-9a1b-2c3d4e5f6a7b",
      "preset": "youtube",
      "status": "queued",
      "progress": 0.42,
      "width": 1080,
      "height": 1920,
      "credits": 12,
      "download_url": "https://<project>.supabase.co/storage/v1/object/sign/media/...",
      "error": null,
      "created_at": "2026-10-10T14:03:22Z",
      "completed_at": "2026-10-10T14:03:22Z"
    }
  ]
}

Get export

GET/exports/{export_id}

Parameters

export_idrequiredpath
string

Responses

200OKExport
404ErrorError

Requestcurl

curl "https://api.capxion.me/v1/exports/EXPORT_ID" \
  -H "Authorization: Bearer $CAPXION_API_KEY"

Response 200json

{
  "id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
  "project_id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
  "batch_id": "e4f5a6b7-c8d9-4e0f-9a1b-2c3d4e5f6a7b",
  "preset": "youtube",
  "status": "queued",
  "progress": 0.42,
  "width": 1080,
  "height": 1920,
  "credits": 12,
  "download_url": "https://<project>.supabase.co/storage/v1/object/sign/media/...",
  "error": null,
  "created_at": "2026-10-10T14:03:22Z",
  "completed_at": "2026-10-10T14:03:22Z"
}

Webhooks

List webhooks

GET/webhooks

Responses

200OKobject

Requestcurl

curl "https://api.capxion.me/v1/webhooks" \
  -H "Authorization: Bearer $CAPXION_API_KEY"

Response 200json

{
  "data": [
    {
      "id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
      "url": "https://hooks.example.com/capxion",
      "events": [
        "project.imported"
      ],
      "created_at": "2026-10-10T14:03:22Z"
    }
  ]
}

Create webhook

POST/webhooks

Body · object

urlrequired
stringuri
HTTPS only
events
EventType[]
Empty or omitted = all events
project.importedproject.import_failedtranscript.completedtranscript.failedexport.completedexport.failed

Responses

201Created. secret is shown only once.WebhookEndpoint & object
400ErrorError

Requestcurl

curl -X POST "https://api.capxion.me/v1/webhooks" \
  -H "Authorization: Bearer $CAPXION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "url": "https://hooks.example.com/capxion",
      "events": [
        "project.imported"
      ]
    }'

Response 201json

{
  "id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
  "url": "https://hooks.example.com/capxion",
  "events": [
    "project.imported"
  ],
  "created_at": "2026-10-10T14:03:22Z",
  "secret": "whsec_..."
}

Delete webhook

DELETE/webhooks/{webhook_id}

Parameters

webhook_idrequiredpath
string

Responses

204Deleted
404ErrorError

Requestcurl

curl -X DELETE "https://api.capxion.me/v1/webhooks/WEBHOOK_ID" \
  -H "Authorization: Bearer $CAPXION_API_KEY"

Account

Get account

GET/account

Responses

200OKobject

Requestcurl

curl "https://api.capxion.me/v1/account" \
  -H "Authorization: Bearer $CAPXION_API_KEY"

Response 200json

{
  "plan": "free",
  "credits": 12,
  "max_upload_mb": 1,
  "max_short_side": 1
}

Webhook event

POSTed as JSON to each matching endpoint. Headers: Capxion-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the endpoint secret>, Capxion-Event-Id, Capxion-Event-Type. Retries with backoff for ~24h on non-2xx; consumers must be idempotent on the event id. See the webhooks guide for verification code.

Eventjson

{
  "id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
  "type": "project.imported",
  "created_at": "2026-10-10T14:03:22Z",
  "data": {
    "project_id": "3f0c7a52-8d7e-4a51-9b1e-2f1c0d6e8a41",
    "export_id": "b81e2d4c-77a0-4c0f-a6f3-5d9e1c2b3a70",
    "job_id": "c5d1e9f0-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "status": "string",
    "error": null
  }
}

Schemas

Errorobject

Properties

errorrequired
object

ProjectStatusenum

importingdrafttranscribingreadyfailed

ProjectKindenum

songpodcastspeechvideoaudio

Aspectenum

16:99:164:51:1

PresetIdenum

youtubeyoutube_shortstiktokinstagram_reelsinstagram_feedlinkedin

EventTypeenum

project.importedproject.import_failedtranscript.completedtranscript.failedexport.completedexport.failed

CaptionStyleobject

Properties

template
enumcleankaraokeboldneonminimal
font
enumInterBricolage GrotesqueMontserratPoppinsBebas NeuePlayfair Display
font_size
number16 to 200
color
stringpattern ^#[0-9a-fA-F]{6}$
highlight
stringpattern ^#[0-9a-fA-F]{6}$
placement
enumtopmiddlebottom
max_lines
integer1 to 3
readable_lines
boolean

CreateProjectobject

Properties

title
stringmax 200 chars
upload_id
string
source_url
stringuri
kind
ProjectKindsongpodcastspeechvideoaudio
language
stringdefault "auto"
text
string
Optional lyrics/script; improves accuracy
format
Aspect16:99:164:51:1
style
CaptionStyle
auto_transcribe
booleandefault true

ResumableUploadobject

TUS 1.0.0 resumable upload target for the same slot as upload_url.

Properties

endpointrequired
stringuri
POST here to create the TUS upload; its Location is where you PATCH and HEAD
headersrequired
object
Send these on every TUS request (POST, PATCH, HEAD). Not your API key.
metadatarequired
object
Upload-Metadata entries for the creation POST (base64-encode each value).
chunk_sizerequired
integer
Bytes per PATCH; every chunk but the last must be exactly this size

Projectobject

Properties

idrequired
string
titlerequired
string
statusrequired
ProjectStatusimportingdrafttranscribingreadyfailed
kindrequired
ProjectKindsongpodcastspeechvideoaudio
sourcerequired
enumaudiovideo
language
string
duration
number | null
format
Aspect16:99:164:51:1
style
CaptionStyle
error
string | null
job_id
string | null
Current import/transcription job
created_atrequired
stringdate-time

Wordobject

Properties

textrequired
string
startrequired
number
endrequired
number

Lineobject

Properties

wordsrequired
Word[]1 to ∞ items

Transcriptobject

Properties

project_idrequired
string
languagerequired
string
durationrequired
number
textrequired
string
linesrequired
Line[]

CreateExportsobject

Properties

presetsrequired
PresetId[]1 to 6 itemsyoutubeyoutube_shortstiktokinstagram_reelsinstagram_feedlinkedin
resolution
enumdefault "1080p"720p1080p2160p
burn_captions
booleandefault true
range_start
numbermin 0
range_end
numbermin 0

Exportobject

Properties

idrequired
string
project_idrequired
string
batch_id
string | null
presetrequired
PresetIdyoutubeyoutube_shortstiktokinstagram_reelsinstagram_feedlinkedin
statusrequired
enumqueuedprocessingcompletedfailed
progressrequired
number0 to 1
width
integer | null
height
integer | null
credits
integer | null
download_url
string | null
Signed URL valid for 1 hour once completed
error
string | null
created_atrequired
stringdate-time
completed_at
string | nulldate-time

Jobobject

Properties

idrequired
string
typerequired
enumimporttranscription
project_idrequired
string
statusrequired
enumqueuedprocessingcompletedfailed
progressrequired
number0 to 1
error
string | null

WebhookEndpointobject

Properties

idrequired
string
urlrequired
string
eventsrequired
EventType[]project.importedproject.import_failedtranscript.completedtranscript.failedexport.completedexport.failed
created_atrequired
stringdate-time

Eventobject

Properties

idrequired
string
typerequired
EventTypeproject.importedproject.import_failedtranscript.completedtranscript.failedexport.completedexport.failed
created_atrequired
stringdate-time
datarequired
object