Carmic Pro API Reference

A user-facing reference for integrating with Carmic Pro from third-party applications (e.g. ApexStream).

• Base URL (production): https://api.carmic.pro/api
• Interactive Swagger: https://api.carmic.pro/api/docs (auto-generated by Django Ninja)
• API version prefix: all endpoints below sit under /v1/
• Format: JSON requests, JSON responses (application/json)
• All response payloads are wrapped as { "data": ..., "meta": {...}? } unless noted

1. Authentication

Carmic uses JWT bearer tokens issued by the Auth router. There is no API-key or service-token mechanism — every caller must log in as a real user.

1.1 Headers required on authenticated calls

A request missing X-Workspace-ID against a workspace-scoped endpoint returns 403 Workspace context required.

1.2 Obtaining a token

POST /v1/auth/login
Content-Type: application/json

{ "email": "[email protected]", "password": "..." }

Response:

{
  "data": {
    "access":  "eyJhbGciOi...",
    "refresh": "eyJhbGciOi...",
    "user":    { "id": "...", "email": "...", "first_name": "", "last_name": "" }
  }
}

The access token is short-lived. Rotate via:

POST /v1/auth/refresh
{ "refresh": "..." }

1.3 Discovering your workspace ID

GET /v1/me
Authorization: Bearer <access>

Returns the user profile and the list of workspaces the user belongs to. Pick the workspace UUID and pass it in the X-Workspace-ID header on every subsequent call.

1.4 Rate limits on auth

2. Quickstart — drive the editor end-to-end

The diagram below is the complete pipeline for: upload a video → let Carmic detect viral clips → render → download. Every step is one HTTP call.

┌─────────────┐   ┌──────────────┐   ┌─────────────────┐   ┌──────────────┐
│ 1. login    │──▶│ 2. create    │──▶│ 3. PUT video to │──▶│ 4. /process  │
│             │   │   project    │   │   presigned R2  │   │   (kick off) │
└─────────────┘   └──────────────┘   └─────────────────┘   └──────┬───────┘
                                                                  │
   ┌──────────────────────────────────────────────────────────────┘
   ▼
┌─────────────┐   ┌──────────────┐   ┌─────────────┐   ┌──────────────┐
│ 5. poll     │──▶│ 6. list      │──▶│ 7. (opt)    │──▶│ 8. /render   │
│   /status   │   │   clips      │   │   PUT clip  │   │              │
└─────────────┘   └──────────────┘   └─────────────┘   └──────┬───────┘
                                                              │
                                ┌─────────────────────────────┘
                                ▼
                       ┌─────────────────┐   ┌──────────────────┐
                       │ 9. poll render  │──▶│ 10. download MP4 │
                       │   progress      │   │   from /video    │
                       └─────────────────┘   └──────────────────┘

Worked example (curl)

# ─── 1. Login ───────────────────────────────────────────────────────
ACCESS=$(curl -s https://api.carmic.pro/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"..."}' \
  | jq -r '.data.access')

# ─── 2. Find workspace id ──────────────────────────────────────────
WS=$(curl -s https://api.carmic.pro/api/v1/me \
  -H "Authorization: Bearer $ACCESS" \
  | jq -r '.data.workspaces[0].id')

# ─── 3. Create project + presigned upload URL ──────────────────────
RESP=$(curl -s https://api.carmic.pro/api/v1/projects/create \
  -H "Authorization: Bearer $ACCESS" -H "X-Workspace-ID: $WS" \
  -H 'Content-Type: application/json' \
  -d '{
    "filename":"podcast.mp4",
    "filesize": 524288000,
    "content_type":"video/mp4",
    "duration": 1800,
    "language":"en",
    "video_type":"podcast"
  }')
PID=$(echo "$RESP" | jq -r '.data.project_id')
URL=$(echo "$RESP" | jq -r '.data.upload_url')

# ─── 4. PUT the video directly to R2 ───────────────────────────────
curl -X PUT --data-binary @podcast.mp4 -H 'Content-Type: video/mp4' "$URL"

# ─── 5. Trigger ingestion ──────────────────────────────────────────
curl -s -X POST https://api.carmic.pro/api/v1/projects/$PID/process \
  -H "Authorization: Bearer $ACCESS" -H "X-Workspace-ID: $WS"

# ─── 6. Poll until clips ready ─────────────────────────────────────
while : ; do
  S=$(curl -s https://api.carmic.pro/api/v1/projects/$PID/status \
        -H "Authorization: Bearer $ACCESS" -H "X-Workspace-ID: $WS")
  echo "$S" | jq -r '.data.current_step + " (" + (.data.progress|tostring) + "%)"'
  [ "$(echo $S | jq -r '.data.status')" = "CLIPS_READY" ] && break
  sleep 10
done

# ─── 7. List clips ─────────────────────────────────────────────────
CLIPS=$(curl -s https://api.carmic.pro/api/v1/projects/$PID \
  -H "Authorization: Bearer $ACCESS" -H "X-Workspace-ID: $WS")
CID=$(echo "$CLIPS" | jq -r '.data.clips[0].id')

# ─── 8. (Optional) save editor template_config — see §5.4 ──────────
# curl -X PUT .../v1/clips/$CID -d @template.json ...

# ─── 9. Render ─────────────────────────────────────────────────────
curl -s -X POST https://api.carmic.pro/api/v1/clips/$CID/render \
  -H "Authorization: Bearer $ACCESS" -H "X-Workspace-ID: $WS"

# ─── 10. Poll render progress + download ───────────────────────────
while : ; do
  P=$(curl -s https://api.carmic.pro/api/v1/clips/$CID/render-progress \
        -H "Authorization: Bearer $ACCESS" -H "X-Workspace-ID: $WS")
  echo "$P" | jq -r '.data.status + " (" + (.data.progress|tostring) + "%)"'
  [ "$(echo $P | jq -r '.data.status')" = "RENDERED" ] && break
  sleep 5
done

curl -L -o clip.mp4 https://api.carmic.pro/api/v1/clips/$CID/video \
  -H "Authorization: Bearer $ACCESS" -H "X-Workspace-ID: $WS"

3. Endpoint reference

Endpoints are grouped by the resource they operate on. Path parameters are shown as {name}. All endpoints require Authorization: Bearer <jwt> + X-Workspace-ID unless explicitly marked Public.

3.1 Auth — /v1/auth/

Password rules: ≥8 chars, ≥1 uppercase, ≥1 lowercase, ≥1 digit.

3.2 Profile & Workspaces — /v1/

3.3 Ingestion — /v1/projects/...

POST /v1/projects/create request body

{
  "filename": "podcast.mp4",         // required
  "filesize": 524288000,             // required, bytes; max 5 GB
  "content_type": "video/mp4",       // mp4 | mov | avi | webm | mkv | mpeg | flv
  "title": "Episode 12",             // optional, defaults to filename stem
  "duration": 1800,                  // seconds, used for billing pre-deduction
  "video_type": "podcast",           // auto | podcast | interview | tutorial | ...
  "language": "en",                  // ISO 639-1
  "language_mode": "single",         // single | multi
  "enable_multimodal": false,        // Gemini Vision pass
  "custom_instructions": "Focus on segments where the guest is laughing",
  "trim_start": 60,                  // optional, skip first 60 s
  "trim_end": 1740                   // optional, stop at 29 min
}

Project status lifecycle

PENDING_UPLOAD → UPLOADING → DOWNLOADING (URL ingest only) →
TRANSCRIBING → PROCESSING → FACE_TRACKING → CLIPS_READY → COMPLETED
                                                       ↘ FAILED / FAILED_DOWNLOAD /
                                                          FAILED_NO_SPEECH /
                                                          FAILED_BILLING /
                                                          FAILED_CORRUPT_VIDEO

Concurrency limits (per workspace):

3.4 Projects — /v1/projects

GET /v1/projects/{id} returns

{
  "data": {
    "id": "...", "title": "...", "status": "CLIPS_READY",
    "duration": 1800, "thumbnail_url": "...",
    "visual_pipeline_ready": true,
    "clips_ready_at": "2026-05-09T12:34:56Z",
    "clip_count": 12,
    "clips": [
      {
        "id": "...", "title": "...",
        "start_time": 142.4, "end_time": 187.9,
        "virality_score": 87, "reasoning": "...",
        "status": "DETECTED",
        "thumbnail_url": "...", "video_url": "...",
        "source_video_url": "https://r2-presigned...",
        "proxy_url": "https://r2-presigned...720p.mp4",
        "broll_suggestions": [...]
      }
    ]
  }
}

3.5 Clips & Editor — /v1/clips

3.5.1 TemplateConfig schema (PUT body)

{
  "layout": {
    "layoutType": "face-track",     // face-track | fit | split
    "padding": 0,
    "backgroundBlur": 20,
    "splitTopSpeaker": "A",
    "safeZoneOverlay": false,
    "aiSpeakerSwitch": true
  },
  "audio": {
    "autoSfxEnabled": false,
    "musicTrack": "none",
    "activeTrack": null,            // {id, url, name, ...} or null
    "musicVolume": 30,
    "voiceVolume": 100,
    "removePauses": false
  },
  "elements": {
    "progressBar": { "enabled": false, "color": "#8b5cf6", "position": "bottom" },
    "watermark":   { "enabled": false, "imageUrl": "", "opacity": 70 },
    "hookTitle":   { "enabled": false, "text": "", "durationSec": 3.0 }
  },
  "style": {
    "captionFont": "Inter",
    "fontSize": 72,
    "lineHeight": 1.2,
    "strokeThickness": 3,
    "captionColor": "#ffffff",
    "highlightColor": "#FFD700",
    "dropShadow": true,
    "shadowIntensity": 50,
    "uppercase": true,
    "captionPosition": "bottom",    // top | middle | bottom | custom
    "yAxisCustomPct": 75,
    "linesPerScreen": 2,            // int | "auto"
    "animationStyle": "pop",
    "animationIntensity": 50,
    "captionBg": "rgba(0,0,0,0)"
  },
  "b_roll": [
    {
      "id": "...",
      "sourceId": "pexels:1234567",
      "videoUrl": "https://...",
      "thumbnailUrl": "https://...",
      "startTime": 12.5,            // position on the clip timeline
      "duration": 4.0,
      "sourceStart": 0,
      "sourceDuration": 0
    }
  ],
  "caption_style": "HORMOZI",
  "shots": [                        // optional — must be zero-gap contiguous
    { "start_time": 0.0, "end_time": 5.0, ...},
    { "start_time": 5.0, "end_time": 10.0, ...}
  ]
}

3.6 B-roll & stock media — /v1/

3.7 Storage — /v1/storage/

3.8 NLE Exports — /v1/

target_format valid values: premiere, davinci, fcpx, after_effects. (logic_pro is intentionally not yet exposed.)

3.9 Templates — /v1/templates

3.10 Media Library — /v1/media

Tier storage caps: FREE 1 GB · STANDARD 10 GB · PROFESSIONAL 50 GB · BUSINESS 100 GB · ENTERPRISE 500 GB.

3.11 Social Accounts — /v1/social

Platforms: youtube, facebook, instagram.

3.12 System & realtime — /v1/

Subscribing to SSE from Node

const ticket = await fetch(`${API}/v1/sse-ticket`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${access}`, 'X-Workspace-ID': ws }
}).then(r => r.json()).then(j => j.ticket)

const es = new EventSource(`${API}/v1/projects/${pid}/stream?ticket=${ticket}`)
es.onmessage = (ev) => console.log(JSON.parse(ev.data))

4. Conventions

4.1 Response envelope

Most success responses look like:

{ "data": <payload>, "meta": { "total": 99, "limit": 20, "offset": 0, "has_more": true } }

meta is only present on listing endpoints.

4.2 Error envelope

{ "error": "Workspace context required (X-Workspace-ID)", "code": 403 }

4.3 Aspect ratios & template presets

caption_style accepted values: HORMOZI, DEFAULT, MINIMAL, IMPACT, KARAOKE, BUBBLE, WHISPER (plus any custom templates returned by /v1/templates).

4.4 Idempotency

• POST /projects/{id}/process is idempotent — calling it on a project already in PROCESSING returns 409.
• POST /clips/{id}/exports is idempotent on (clip_id, target_format) — duplicate calls return the existing export_id.
• Project creation deducts billing minutes once per project ID.

5. Integrating from ApexStream

5.1 Auth bootstrap (one-time setup)

ApexStream needs a dedicated service user in Carmic (Carmic does not currently issue API keys). Suggested setup:

1. Have the Carmic admin create a workspace apexstream and a user [email protected] with EDITOR or OWNER role.
2. Store CARMIC_SVC_EMAIL, CARMIC_SVC_PASSWORD in ApexStream secret manager.
3. On boot, ApexStream POSTs to /v1/auth/login, caches access (~30 min) and refresh (long-lived). On 401 → call /v1/auth/refresh; on refresh failure → re-login.
4. Cache the workspace UUID from /v1/me and inject X-Workspace-ID on every request.

5.2 Reference TypeScript client (sketch)

class CarmicClient {
  constructor(
    private base = 'https://api.carmic.pro/api',
    private email: string,
    private password: string,
  ) {}

  private access?: string
  private refresh?: string
  private workspaceId?: string

  async ensureSession() {
    if (this.access) return
    const r = await fetch(`${this.base}/v1/auth/login`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: this.email, password: this.password }),
    }).then(r => r.json())
    this.access = r.data.access
    this.refresh = r.data.refresh

    const me = await this.get('/v1/me')
    this.workspaceId = me.data.workspaces[0].id
  }

  private headers() {
    return {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${this.access}`,
      'X-Workspace-ID': this.workspaceId!,
    }
  }

  async createProject(input: { filename: string; filesize: number; duration: number; language?: string }) {
    await this.ensureSession()
    const r = await fetch(`${this.base}/v1/projects/create`, {
      method: 'POST', headers: this.headers(),
      body: JSON.stringify(input),
    }).then(r => r.json())
    return r.data as { project_id: string; upload_url: string; object_key: string }
  }

  async putToR2(uploadUrl: string, body: Buffer | Blob, contentType = 'video/mp4') {
    await fetch(uploadUrl, {
      method: 'PUT',
      headers: { 'Content-Type': contentType },
      body,
    })
  }

  async startProcessing(projectId: string) {
    await fetch(`${this.base}/v1/projects/${projectId}/process`, {
      method: 'POST', headers: this.headers(),
    })
  }

  async waitForClips(projectId: string, pollMs = 10_000): Promise<string[]> {
    while (true) {
      const s = await this.get(`/v1/projects/${projectId}/status`)
      if (s.data.status === 'CLIPS_READY' || s.data.status === 'COMPLETED') break
      if (s.data.status?.startsWith('FAILED')) throw new Error(s.data.status)
      await new Promise(r => setTimeout(r, pollMs))
    }
    const p = await this.get(`/v1/projects/${projectId}`)
    return p.data.clips.map((c: any) => c.id)
  }

  async render(clipId: string) {
    return fetch(`${this.base}/v1/clips/${clipId}/render`, {
      method: 'POST', headers: this.headers(),
    }).then(r => r.json())
  }

  // ... waitForRender, downloadMp4, exportPremiere, etc.
}

5.3 Quotas you need to plan around

If ApexStream submits a bulk batch, queue your own jobs and pace project creation ≤ 5/min. Use the SSE stream rather than polling whenever you can — it keeps latency under a second on the CLIPS_READY transition.

5.4 Driving the editor without a browser

Yes — the editor UI is a thin front over the same PUT /v1/clips/{id} endpoint. ApexStream can:

• Pre-fetch the default template_config from GET /v1/clips/{id}.
• Mutate any of the fields in §3.5.1 (e.g. set caption_style: "HORMOZI", swap fonts/colors, add b_roll[], set elements.watermark).
• Save with PUT /v1/clips/{id} then call POST /v1/clips/{id}/render.

The only flows that today still depend on the UI are:

• OAuth-based social uploads — POST /v1/social/connect/{platform} returns a consent URL the end-user has to visit in a browser. ApexStream can complete the OAuth callback server-side, but the consent click itself must happen in a user agent.

Everything else — upload, analyze, edit template, render, NLE export, download — is fully scriptable.

6. Editor-via-API: feasibility summary for ApexStream

Verdict: ApexStream can drive the entire Carmic editor end-to-end via this API. The two real integration costs are (a) the user-bearer-only auth model — handled by a dedicated service user — and (b) the absence of completion webhooks — handled by the SSE streams.