Everpop Clip API

openapi: 3.2.0
info:
  title: Everpop Clip API
  version: 1.3.1
  description: 'Turn your own videos into published Shorts for YouTube, Instagram, Facebook and TikTok, with measured receipts on eligible YouTube Shorts. Built to be driven by AI agents: upload a file, clip it, publish it, and pull real 48h/7d performance — all by API. REST and MCP need the Pro or Scale plan; other accounts get HTTP 402 with reason subscription (no active subscription) or plan (the plan doesn''t include API access). Full agent guide: https://everpop.app/skill.md · MCP connector: https://everpop.app/api/mcp/mcp (OAuth, or Authorization: Bearer epk_...)'
  termsOfService: https://everpop.app/terms
  x-changelog:
  - version: 1.3.1
    date: '2026-10-16'
    changes: 'Changed: when no natural sentence end fits a clip, it can now end on a held final frame, flagged open_ending in qcWarnings (one whose hold could not land is flagged mid_sentence_end); both wait for review and never auto-post. A render whose clips all end that way hands its video back, so GET /api/v1/usage does not count it. A video gets one uncharged render a month, shared with repeat-only renders, whichever came first.'
  - version: 1.3.0
    date: '2026-10-08'
    changes: 'Changed: POST /api/v1/clip on a video whose strong moments were all clipped already completed FAILED with nothing new to clip; it now completes with one clip that reuses the best of them, flagged repeat_moment in qcWarnings. The first such render of a video in a month hands its video back, so GET /api/v1/usage does not count it. Automatic renders keep the old answer.'
  - version: 1.2.0
    date: '2026-10-01'
    changes: 'Changed: the upload size limit was 4 GB and is now 32 GB. POST /api/v1/videos/upload answered 413 file_too_large for a file over 4 GB; it now takes a file up to 5 GB, the most one PUT can carry. A file over 5 GB and up to 32 GB answers 413 file_too_large with reason single_put and browserUploadUrl: the user uploads it in the browser. A file over 32 GB still answers 413 file_too_large. Added: browserUploadUrl on that error body.'
  - version: 1.1.0
    date: '2026-09-24'
    changes: 'Changed: a 401 answered code unauthorized and now names its case: key_missing, key_invalid or key_expired. The Instagram posting-safety cap answered 429 rate_limited and now answers posting_cap. A 429 sent Retry-After: 60 whatever its cause; it now fits the cause (the seconds until resetsAt for quota_exhausted, 180 for queue_capacity, none for upload_cleanup_backlog, upload_retention_backlog and posting_cap, which carry retryable: false). A method a route does not support answered an empty 405; it now answers 405 method_not_allowed with an Allow header. Added: error bodies document their detail fields and a list of known codes (ErrorCode), including meta_publish_frozen. GET /api/v1/posts takes clipId. generateShort is marked deprecated while paused. Examples on the upload, finalize, clip, job, publish and receipts operations.'
  - version: 1.0.0
    date: '2026-07-03'
    changes: First published spec.
  contact:
    email: support@everpop.app
    url: https://everpop.app/contact
servers:
- url: https://everpop.app
security:
- apiKey: []
tags:
- name: Clip
paths:
  /api/v1/clip:
    post:
      operationId: clipVideo
      summary: Clip the best moments from one of the user's videos into vertical Shorts
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
        description: Retries carrying the same key never mint a second metered render; reusing a key with different options is a 409 idempotency_conflict.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - sourceVideoId
              properties:
                sourceVideoId:
                  type: string
                  description: 'A video from GET /api/v1/videos with clippable: true.'
                prompt:
                  type: string
                  minLength: 3
                  maxLength: 300
                  description: Optional steer, e.g. 'the most surprising moment' — omit and the AI picks
                clipCount:
                  type: integer
                  minimum: 1
                  maximum: 20
                  description: How many clips. Omit for the account's saved clip count (3 if unset). Capped by the plan's clips per video (Starter 3, Pro 10, Scale 15); the response's clipCountApplied says what the job runs with.
                captionStyle:
                  type: string
                  enum:
                  - pop
                  - boxed
                  - minimal
                  - clean
                  - hormozi
                language:
                  type:
                  - string
                  - 'null'
                  pattern: ^[a-z]{2}$
                  description: Omit to use the saved language choice (English text by default). Null explicitly selects English captions, headlines and hooks with auto-detected speech (non-English speech is translated). A lowercase ISO-639-1 code such as bg pins that spoken language and keeps text native — so en means the speech IS English; never send en for non-English speech. Original audio is retained.
                archetype:
                  type: string
                  enum:
                  - top_moments
                  - summary
                  - punch
                  - action
                  - all
                  description: Editorial cut; all = a Summary, a Top-moment and a Punch from one pass. Omit for the normal best-moments pick.
                targetSeconds:
                  type: integer
                  minimum: 10
                  maximum: 180
                aspectRatio:
                  type: string
                  enum:
                  - '9:16'
                  - '1:1'
                  - '16:9'
                  - '4:5'
                  description: The rendered frame. Omit for the account's saved setting (9:16 if unset). The response's aspectRatio says what the job renders at.
                captionsEnabled:
                  type: boolean
                  description: Burn captions into the clips. Omit for the account's saved setting (on if unset). The response's captionsEnabled says what the job applied.
            examples:
              twoClips:
                value:
                  sourceVideoId: cm1video000000000000000000
                  prompt: the most surprising moment, ending on a cliffhanger
                  clipCount: 2
                  targetSeconds: 45
                  captionStyle: pop
      responses:
        '200':
          description: Render started — poll the returned job. clipCountApplied, aspectRatio and captionsEnabled are the values the job runs with.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClipJobRefEnvelope'
              examples:
                started:
                  value:
                    ok: true
                    data:
                      jobId: cm1job00000000000000000000
                      status: PENDING
                      poll: /api/v1/jobs/cm1job00000000000000000000
                      clipCountApplied: 2
                      aspectRatio: '9:16'
                      captionsEnabled: true
        '404':
          description: Source video not found for this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: code=idempotency_conflict — the Idempotency-Key was already used with different options.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          $ref: '#/components/responses/UploadRequired'
        '429':
          description: 'code=rate_limited (Retry-After 60); code=quota_exhausted (monthly videos used up; retryable: false, Retry-After = seconds until resetsAt — tell the user); or code=queue_capacity (render queue full; retryable: true, Retry-After 180).'
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          description: code=engine_offline — the clipping service is briefly unavailable; nothing was charged and the attempt is recorded as a failed job. Retry the same request in a few minutes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      tags:
      - Clip
components:
  schemas:
    ClipJobRefEnvelope:
      type: object
      properties:
        ok:
          const: true
        data:
          $ref: '#/components/schemas/ClipJobRef'
      required:
      - ok
      - data
    ErrorCode:
      type: string
      description: 'Codes an agent branches on, each explained in https://everpop.app/skill.md (Error codes). The list grows additively: handle a code that is not listed by its HTTP status.'
      enum:
      - bad_request
      - unauthorized
      - key_missing
      - key_invalid
      - key_expired
      - payment_required
      - subscription
      - plan
      - forbidden
      - scope
      - suspended
      - disabled
      - content_review
      - not_found
      - method_not_allowed
      - conflict
      - idempotency_conflict
      - clip_removed
      - upload_not_ready
      - file_too_large
      - unprocessable
      - validation_failed
      - invalid_cursor
      - upload_required
      - generated_source
      - demo_source
      - unknown_destination
      - no_eligible_destination
      - clip_not_ready
      - rights_unconfirmed
      - rate_limited
      - quota_exhausted
      - queue_capacity
      - upload_slots
      - upload_cleanup_backlog
      - upload_retention_backlog
      - posting_cap
      - internal_error
      - upstream_error
      - unavailable
      - engine_offline
      - meta_publish_frozen
      - cleanup_pending
    ErrorEnvelope:
      type: object
      properties:
        ok:
          const: false
        error:
          type: string
          description: Human-readable; safe to show the user.
        reason:
          type: string
          description: 'Kept for compatibility where it existed (e.g. subscription, plan, scope, unknown_destination, content_review). With code=file_too_large, single_put: the file is over 5 GB, the most one PUT can carry, and within the 32 GB limit.'
        code:
          anyOf:
          - $ref: '#/components/schemas/ErrorCode'
          - type: string
          description: 'Stable machine code, on every error: the specific code (e.g. upload_required, quota_exhausted, invalid_cursor, file_too_large), else the reason, else by status (bad_request, not_found, rate_limited, internal_error, …). Branch on this.'
        retryable:
          type: boolean
          description: 'On some 429s. false (quota_exhausted, upload_cleanup_backlog, upload_retention_backlog, posting_cap): waiting a minute will not help; stop and tell the user. true (queue_capacity): retry after Retry-After.'
        issues:
          type: object
          description: 'With code=validation_failed: the field errors ({ formErrors, fieldErrors }).'
        used:
          type: integer
          description: 'With code=quota_exhausted: videos (or AI shorts) used in the current window.'
        limit:
          type: integer
          description: 'With code=quota_exhausted: the plan''s monthly allowance.'
        resetsAt:
          type: string
          format: date-time
          description: 'With code=quota_exhausted: when the allowance resets.'
        scope:
          type: string
          enum:
          - videos
          - generations
          - user
          - global
          description: 'With code=quota_exhausted: which allowance (videos or generations). With code=queue_capacity: whose queue is full (user or global).'
        destinationIds:
          type: array
          items:
            type: string
          description: 'With code=unknown_destination: the requested ids that are not connected and healthy.'
        uploadUrl:
          type: string
          format: uri
          description: 'With code=upload_required: the sign-in-gated page where the user uploads this video''s file.'
        browserUploadUrl:
          type: string
          format: uri
          description: 'With code=file_too_large and reason=single_put: the sign-in-gated page where the user uploads the file (up to 32 GB).'
      required:
      - ok
      - error
      - code
    PaywallError:
      type: object
      properties:
        ok:
          const: false
        error:
          type: string
        reason:
          type: string
          enum:
          - subscription
          - plan
        code:
          type: string
          enum:
          - subscription
          - plan
          description: The same value as reason.
      required:
      - ok
      - error
      - reason
      - code
    ClipJobRef:
      type: object
      properties:
        jobId:
          type: string
        status:
          type: string
          enum:
          - PENDING
          - PROCESSING
          - COMPLETED
          - FAILED
          - CANCELED
        poll:
          type: string
          description: Relative URL to poll, e.g. /api/v1/jobs/{id}
        clipCountApplied:
          type:
          - integer
          - 'null'
          description: The clip count the job runs with after the plan's per-video cap (1 for a Summary or Punch, which deliver one video).
        aspectRatio:
          type:
          - string
          - 'null'
          enum:
          - '9:16'
          - '1:1'
          - '16:9'
          - '4:5'
          - null
          description: 'The aspect ratio the job renders at: the request''s aspectRatio, or the account''s saved setting when it was omitted.'
        captionsEnabled:
          type:
          - boolean
          - 'null'
          description: 'Whether the job burns captions in: the request''s captionsEnabled, or the account''s saved setting when it was omitted.'
      required:
      - jobId
      - status
      - poll
      - clipCountApplied
      - aspectRatio
      - captionsEnabled
  responses:
    Forbidden:
      description: 'code=scope (also reason=scope): the API key is read-only and this is a write. code=suspended: the account is suspended. Endpoint-specific refusals document their own reason.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    PaymentRequired:
      description: 'REST and MCP need the Pro or Scale plan. reason=subscription: the account has no active subscription (subscribe, or redeem an invite code). reason=plan: the account''s plan doesn''t include this (API and agent access need Pro or Scale).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaywallError'
    Unauthorized:
      description: 'The API key did not authenticate. code=key_missing: no Authorization: Bearer epk_... header. code=key_invalid: the key is unknown or revoked. code=key_expired: the key passed its expiry; the user creates a new one in Dashboard → API.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    UploadRequired:
      description: '422 with body.code: upload_required — this video''s source is a YouTube URL and Everpop never downloads from YouTube; upload the file via POST /api/v1/videos/upload (+ /complete with linkSourceVideoId to attach it to this video), then clip. The body also carries uploadUrl, the sign-in-gated page where the user can upload the file themselves (for agents that can''t send bytes). generated_source — a generated short''s synthetic source (use /api/v1/generate). demo_source — Everpop''s sample. validation_failed — the body did not validate. GET /api/v1/videos reports the first three ahead of time as clippable: false + notClippableReason.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  headers:
    RetryAfter:
      description: 'Seconds to wait before retrying: 60 for a per-minute rate limit (rate_limited, upload_slots), 180 for queue_capacity, the seconds until resetsAt for quota_exhausted. Absent on upload_cleanup_backlog, upload_retention_backlog and posting_cap, where waiting will not help soon.'
      schema:
        type: integer
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: epk_...
      description: Per-user API key from everpop.app/dashboard/api (Dashboard → API). Write scope required for mutating endpoints.