Subscut Generate Short API documentation

This API is asynchronous. You do not get the final rendered video in the first response. Instead, you create a job, receive a job_id, then poll the same endpoint until the job becomes completed or failed.

Supported output controls currently cover aspect ratio, caption style, hook enablement and position, b-roll enablement, basic transition style, branding, and trim range.

You can authenticate in either of these ways:

• Send x-api-key: your_key for server-to-server or agent calls.
• Use an existing authenticated web or mobile session.

API keys can be created from Dashboard API Access.

1. Upload your source video somewhere publicly reachable over HTTP or HTTPS.
2. Send a create-job request to /api/generate-short.
3. Read the returned job_id.
4. Poll the same endpoint with { "job_id": "..." }.
5. Stop polling when the status becomes completed or failed.

This is the full public request shape. All fields except video_url are optional.

{
  "video_url": "https://example.com/source-video.mp4",
  "aspect_ratio": "9:16",
  "captions": {
    "enabled": true,
    "style": "beast",
    "highlight_keywords": true,
    "font_size": "auto"
  },
  "hook": {
    "enabled": true,
    "text": "",
    "position": "top"
  },
  "broll": {
    "enabled": false,
    "source": "stock"
  },
  "transitions": {
    "enabled": true,
    "style": "fast_cut"
  },
  "branding": {
    "logo_url": "",
    "watermark": ""
  },
  "trim": {
    "start": 0,
    "end": null
  }
}

Create-job response:

{
  "status": "processing",
  "video_url": null,
  "thumbnail_url": null,
  "duration": null,
  "job_id": "ck_example_job_id"
}

Completed job response:

{
  "status": "completed",
  "video_url": "https://res.cloudinary.com/.../rendered.mp4",
  "thumbnail_url": "https://res.cloudinary.com/.../thumbnail.jpg",
  "duration": 21.83,
  "job_id": "ck_example_job_id"
}

Failed job response:

{
  "status": "failed",
  "video_url": null,
  "thumbnail_url": null,
  "duration": null,
  "job_id": "ck_example_job_id",
  "error_code": "INVALID_VIDEO_URL",
  "error_message": "`video_url` must be a valid HTTP or HTTPS URL."
}

Current error codes:

• INVALID_VIDEO_URL
• VIDEO_TOO_LONG
• PROCESSING_FAILED
• UNSUPPORTED_FORMAT
• UNAUTHORIZED

Create a job:

curl -X POST https://subscut.com/api/generate-short \
  -H "Content-Type: application/json" \
  -H "x-api-key: subscut_your_api_key" \
  -d '{
    "video_url": "https://example.com/source-video.mp4",
    "aspect_ratio": "9:16",
    "captions": {
      "enabled": true,
      "style": "beast",
      "highlight_keywords": true,
      "font_size": "auto"
    },
    "hook": {
      "enabled": true,
      "text": "3 mistakes killing your retention",
      "position": "top"
    },
    "broll": {
      "enabled": false,
      "source": "stock"
    },
    "transitions": {
      "enabled": true,
      "style": "fast_cut"
    },
    "branding": {
      "logo_url": "https://example.com/logo.png",
      "watermark": "subscut"
    },
    "trim": {
      "start": 0,
      "end": 22
    }
  }'

Poll a job:

curl -X POST https://subscut.com/api/generate-short \
  -H "Content-Type: application/json" \
  -H "x-api-key: subscut_your_api_key" \
  -d '{
    "job_id": "ck_example_job_id"
  }'

• Caption x and y positioning is not currently exposed in the public request schema.
• You cannot currently provide your own manual caption chunks or word-level timings through this endpoint.
• Hook positioning only supports top and center.
• Supported video length is capped at 120 seconds.
• video_url must be reachable by the server. Local filesystem paths or private localhost URLs will not work.

If you want another model or agent to call the API reliably, give it this compact contract:

Endpoint: POST /api/generate-short
Auth: x-api-key header or existing authenticated web/mobile session
Mode 1: Create job by sending a GenerateShortRequest JSON body
Mode 2: Poll job by sending { "job_id": "..." }

Required field for create:
- video_url: public http/https URL pointing to a supported video file

Optional groups:
- aspect_ratio: "9:16" | "1:1" | "16:9"
- captions.enabled: boolean
- captions.style: "beast" | "leon" | "hormozi" | "mrbeast" | "clean" | "minimal"
- captions.highlight_keywords: boolean
- captions.font_size: "auto" | "small" | "medium" | "large"
- hook.enabled: boolean
- hook.text: string
- hook.position: "top" | "center"
- broll.enabled: boolean
- broll.source: "stock" | "ai"
- transitions.enabled: boolean
- transitions.style: "fast_cut" | "smooth" | "zoom"
- branding.logo_url: string
- branding.watermark: string
- trim.start: number >= 0
- trim.end: number | null and must be > trim.start when present

Current limitation:
- public request schema does not support caption x/y positioning
- public request schema does not accept manual caption text/chunks
- hook can be disabled entirely by setting hook.enabled to false