EditClips.online Jobs API

openapi: 3.2.0
info:
  title: Editclips Online Jobs API
  version: '1.0'
  contact:
    name: EditClips
    url: https://editclips.online
  description: 'Operations tagged Jobs across 2 of this provider''s published API definitions: editclips-online-openapi.yaml, openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://editclips.online/api/v1
  description: Production
security:
- BearerAuth: []
tags:
- name: Jobs
  description: Create, poll, list, and cancel processing jobs
paths:
  /jobs:
    post:
      operationId: createJob
      summary: Create a job
      description: 'Submit a file for processing. Provide input files in one of two ways:


        **Option 1: URL inputs** — Pass `inputs` with public URLs. The job is queued immediately.


        **Option 2: File upload** — Pass `files` with filenames and sizes. The response includes

        presigned `uploads` URLs. Upload your files via PUT, then call `POST /jobs/{id}/ready` to

        start processing.


        Provide either `inputs` or `files`, not both.


        Needs a paid plan (Lite or higher), checked on every call. Nothing is reserved: non-AI tools

        are included in the plan, and an AI result is charged its credits once, when it''s ready.

        For an AI tool the balance must cover the estimate from `durationMs`, `width` and `height`

        (`estimatedCredits` in the response) or the job is refused with `402`. The final price comes

        from the finished file; if it is more than your balance, the job completes but stays locked

        until a top-up (see `GET /jobs/{id}`).'
      tags:
      - Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJobRequest'
            examples:
              urlInput:
                summary: URL input (queued immediately)
                value:
                  tool: convert-video
                  inputs:
                  - https://example.com/video.mov
                  options:
                    format: h264
                  durationMs: 120000
                  width: 1920
                  height: 1080
                  webhook: https://yourapp.com/webhooks/editclips
              fileUpload:
                summary: File upload (returns presigned URLs)
                value:
                  tool: convert-video
                  files:
                  - name: video.mov
                    size: 52428800
                  durationMs: 120000
                  width: 1920
                  height: 1080
      responses:
        '201':
          description: Job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobCreated'
              examples:
                queued:
                  summary: URL input — queued immediately
                  value:
                    id: d290f1ee-6c54-4b01-90e6-d701748f0851
                    status: queued
                    tool: convert-video
                    creditsReserved: 0
                    estimatedCredits: 0
                    poll: /api/v1/jobs/d290f1ee-6c54-4b01-90e6-d701748f0851
                pendingUpload:
                  summary: File upload — presigned URLs returned
                  value:
                    id: d290f1ee-6c54-4b01-90e6-d701748f0851
                    status: pending_upload
                    tool: convert-video
                    creditsReserved: 0
                    estimatedCredits: 0
                    uploads:
                    - name: video.mov
                      url: https://account.r2.cloudflarestorage.com/editclips-processing/jobs/d290f1ee-.../input/0-video.mov?X-Amz-Expires=1800&...
                    poll: /api/v1/jobs/d290f1ee-6c54-4b01-90e6-d701748f0851
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unknownTool:
                  summary: Invalid tool slug
                  value:
                    error: Unknown tool
                    tools: GET /api/v1/tools
                missingInputs:
                  summary: Missing inputs or files
                  value:
                    error: Provide inputs (array of URLs) or files (array of {name, size} for upload)
                wrongInputCount:
                  summary: Wrong input count
                  value:
                    error: Tool 'convert-video' accepts 1 input(s)
                invalidUrl:
                  summary: Invalid URL
                  value:
                    error: 'Invalid input URL: not-a-url'
                durationExceeded:
                  summary: Duration too long
                  value:
                    error: Input exceeds maximum duration of 60 minutes
                webhookNotHttps:
                  summary: Non-HTTPS webhook
                  value:
                    error: Webhook URL must use HTTPS
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: An AI job whose estimated price is more than your balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Insufficient credits
                code: insufficient_credits
                required: 25
                balance: 12
                pricing: https://editclips.online/pricing
        '403':
          description: No paid plan on the key's account, or a webhook without Pro or Business
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                planRequired:
                  summary: The account has no paid plan
                  value:
                    error: API keys need a paid plan (Lite or higher)
                    code: plan_required
                    plan: Free
                    pricing: https://editclips.online/pricing
                webhooks:
                  summary: Webhooks need Pro or Business
                  value:
                    error: Webhooks require a Pro or Business plan
        '429':
          description: Too many concurrent jobs or rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                concurrentLimit:
                  summary: Too many active jobs
                  value:
                    error: Maximum 5 concurrent jobs
                rateLimit:
                  summary: Rate limited
                  value:
                    error: Rate limit exceeded
    get:
      operationId: listJobs
      summary: List jobs
      description: Returns your jobs, newest first. Only jobs created with the current API key are returned.
      tags:
      - Jobs
      parameters:
      - name: status
        in: query
        description: Filter by job status
        schema:
          type: string
          enum:
          - pending_upload
          - queued
          - processing
          - completed
          - failed
          - cancelled
      - name: limit
        in: query
        description: Maximum number of jobs to return (1-100)
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Job list
          content:
            application/json:
              schema:
                type: object
                required:
                - jobs
                properties:
                  jobs:
                    type: array
                    items:
                      $ref: '#/components/schemas/JobSummary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://editclips.online/api/v1
      description: Production
  /jobs/{id}/ready:
    post:
      operationId: markJobReady
      summary: Mark upload complete
      description: 'After uploading all files to the presigned URLs from `POST /jobs`, call this endpoint

        to start processing. Only valid for jobs with status `pending_upload`.


        The job transitions to `queued` and enters the processing pipeline. Like creating a job,

        this needs a paid plan (Lite or higher).'
      tags:
      - Jobs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Job queued for processing
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - status
                properties:
                  id:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum:
                    - queued
              example:
                id: d290f1ee-6c54-4b01-90e6-d701748f0851
                status: queued
        '400':
          description: Job is not awaiting upload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Job is not awaiting upload
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/PlanRequired'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Job not found
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://editclips.online/api/v1
      description: Production
  /jobs/{id}:
    get:
      operationId: getJob
      summary: Get a job
      description: 'Retrieve the current status of a job. Poll this endpoint until `status` is `completed` or `failed`.


        When completed, `outputUrl` contains a presigned R2 download link valid for 1 hour — once the

        result is unlocked. Non-AI results are included in your plan; an AI result is charged its

        credits once, when it''s ready. If your balance couldn''t cover it then, the job is completed but

        locked: this answers `402` with `outputUrl: null`, `code: insufficient_credits` and the credits

        `required` against your `balance`. Each request tries again, so after a top-up the next one

        charges the credits and returns the link. (`code: plan_required` means the account''s plan

        lapsed and the result is past what a free account downloads.)'
      tags:
      - Jobs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        example: d290f1ee-6c54-4b01-90e6-d701748f0851
      responses:
        '200':
          description: Job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
              example:
                id: d290f1ee-6c54-4b01-90e6-d701748f0851
                status: completed
                tool: convert-video
                progress: 100
                progressMessage: null
                errorMessage: null
                creditsReserved: 0
                creditsCharged: 0
                createdAt: '2026-03-01T12:00:00.000Z'
                completedAt: '2026-03-01T12:01:23.000Z'
                outputUrl: https://r2.editclips.online/jobs/...
                outputFilename: video.mp4
                outputSize: 10485760
                metrics:
                  wallTimeMs: 83000
                  cpuTimeMs: 72000
                  peakMemoryBytes: 536870912
                  estimatedCostMicroUsd: 1250
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Completed, but locked until the balance covers the result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LockedJob'
              example:
                id: d290f1ee-6c54-4b01-90e6-d701748f0851
                status: completed
                tool: video-remove-background
                progress: 100
                progressMessage: null
                errorMessage: null
                creditsReserved: 0
                creditsCharged: 0
                createdAt: '2026-03-01T12:00:00.000Z'
                completedAt: '2026-03-01T12:01:23.000Z'
                outputUrl: null
                outputFilename: video.webm
                outputSize: 10485760
                error: Insufficient credits
                code: insufficient_credits
                required: 25
                balance: 12
                pricing: https://editclips.online/pricing
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Job not found
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      operationId: cancelJob
      summary: Cancel a job
      description: 'Cancel a job that is `pending_upload`, `queued`, or `processing`. A cancelled job costs nothing.


        Jobs that are already `completed`, `failed`, or `cancelled` cannot be cancelled.'
      tags:
      - Jobs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Job cancelled
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - status
                properties:
                  id:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum:
                    - cancelled
              example:
                id: d290f1ee-6c54-4b01-90e6-d701748f0851
                status: cancelled
        '400':
          description: Job already finished
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Job already finished
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Job not found
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://editclips.online/api/v1
      description: Production
webhooks:
  jobCompleted:
    post:
      operationId: webhookJobCompleted
      summary: job.completed
      description: 'Sent to your webhook URL when a job finishes successfully.

        The `outputUrl` is a presigned R2 download link valid for **1 hour**, sent only once the

        result is unlocked: non-AI results are included in your plan, AI results are charged their

        credits when they''re ready. If your balance can''t cover an AI result, `outputUrl` is `null`

        and `download` says what''s needed — top up, then `GET /jobs/{id}` to download it.'
      tags:
      - Jobs
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - event
              - job
              properties:
                event:
                  type: string
                  enum:
                  - job.completed
                job:
                  type: object
                  required:
                  - id
                  - tool
                  - status
                  - outputUrl
                  - outputFilename
                  - outputSize
                  - creditsCharged
                  properties:
                    id:
                      type: string
                      format: uuid
                    tool:
                      type: string
                    status:
                      type: string
                      enum:
                      - completed
                    outputUrl:
                      type: string
                      format: uri
                      nullable: true
                      description: Presigned download URL (valid 1 hour); null while the result is locked
                    outputFilename:
                      type: string
                    outputSize:
                      type: integer
                      description: File size in bytes
                    creditsCharged:
                      type: integer
                      description: AI credits charged for the result (0 for non-AI tools)
                    download:
                      type: object
                      description: Only while the result is locked
                      required:
                      - reason
                      - required
                      - balance
                      properties:
                        reason:
                          type: string
                          enum:
                          - insufficient_credits
                          - plan_required
                        required:
                          type: integer
                          nullable: true
                          description: Credits the download costs (null when a plan is what's missing)
                        balance:
                          type: integer
                        why:
                          type: string
                          enum:
                          - daily-limit
                          - too-long
                          - too-large
                          description: With plan_required — why a free account can't download it
                    message:
                      type: string
                      description: Only while the result is locked — what to do to download it
                    metrics:
                      $ref: '#/components/schemas/Metrics'
            examples:
              unlocked:
                summary: Result unlocked — the file is attached
                value:
                  event: job.completed
                  job:
                    id: d290f1ee-6c54-4b01-90e6-d701748f0851
                    tool: convert-video
                    status: completed
                    outputUrl: https://r2.editclips.online/jobs/...
                    outputFilename: video.mp4
                    outputSize: 10485760
                    creditsCharged: 0
                    metrics:
                      wallTimeMs: 83000
                      cpuTimeMs: 72000
                      peakMemoryBytes: 536870912
                      estimatedCostMicroUsd: 1250
              locked:
                summary: AI result the balance can't cover — no file until a top-up
                value:
                  event: job.completed
                  job:
                    id: d290f1ee-6c54-4b01-90e6-d701748f0851
                    tool: video-remove-background
                    status: completed
                    outputUrl: null
                    outputFilename: video.webm
                    outputSize: 10485760
                    creditsCharged: 0
                    download:
                      reason: insufficient_credits
                      required: 25
                      balance: 12
                    message: This result costs 25 AI credits and the balance is 12. Top up at https://editclips.online/pricing, then GET /api/v1/jobs/d290f1ee-6c54-4b01-90e6-d701748f0851 to download it.
                    metrics: null
      responses:
        '200':
          description: Webhook acknowledged
    servers:
    - url: https://editclips.online/api/v1
      description: Production
  jobFailed:
    post:
      operationId: webhookJobFailed
      summary: job.failed
      description: 'Sent to your webhook URL when a job permanently fails.

        A failed job costs nothing.'
      tags:
      - Jobs
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - event
              - job
              properties:
                event:
                  type: string
                  enum:
                  - job.failed
                job:
                  type: object
                  required:
                  - id
                  - tool
                  - status
                  - errorMessage
                  properties:
                    id:
                      type: string
                      format: uuid
                    tool:
                      type: string
                    status:
                      type: string
                      enum:
                      - failed
                    errorMessage:
                      type: string
            example:
              event: job.failed
              job:
                id: d290f1ee-6c54-4b01-90e6-d701748f0851
                tool: convert-video
                status: failed
                errorMessage: 'FFmpeg exited with code 1: Invalid input format'
      responses:
        '200':
          description: Webhook acknowledged
    servers:
    - url: https://editclips.online/api/v1
      description: Production
components:
  schemas:
    JobSummary:
      type: object
      required:
      - id
      - status
      - toolSlug
      - creditsReserved
      - createdAt
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - pending_upload
          - queued
          - processing
          - completed
          - failed
          - cancelled
        toolSlug:
          type: string
        progress:
          type: integer
          minimum: 0
          maximum: 100
        progressMessage:
          type: string
          nullable: true
        errorMessage:
          type: string
          nullable: true
        outputFilename:
          type: string
          nullable: true
        outputSize:
          type: integer
          nullable: true
        minutesCharged:
          type: integer
          nullable: true
          description: AI credits charged for the result
        creditsReserved:
          type: integer
          description: Always 0 — nothing is held when a job is created
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
          nullable: true
    CreateJobRequest:
      type: object
      required:
      - tool
      properties:
        tool:
          type: string
          description: Tool slug from `GET /api/v1/tools`
          example: convert-video
        inputs:
          type: array
          items:
            type: string
            format: uri
          description: Public URLs to input files. Most tools accept 1 input; some (merge, combine) accept multiple. Mutually exclusive with `files`.
          example:
          - https://example.com/video.mov
        files:
          type: array
          description: Files to upload. The response will include presigned upload URLs. After uploading, call `POST /jobs/{id}/ready`. Mutually exclusive with `inputs`.
          items:
            type: object
            required:
            - name
            properties:
              name:
                type: string
                description: Filename with extension
                example: video.mov
              size:
                type: integer
                description: File size in bytes (optional, for bookkeeping)
                example: 52428800
          example:
          - name: video.mov
            size: 52428800
        options:
          type: object
          additionalProperties: true
          description: Key-value pairs matching the tool's option keys. Omitted options use their defaults.
          example:
            format: h264
        webhook:
          type: string
          format: uri
          description: HTTPS URL to receive a POST when the job completes or fails
          example: https://yourapp.com/webhooks/editclips
        durationMs:
          type: integer
          description: Input duration in milliseconds (for credit estimation). Max 3,600,000 (60 min).
          maximum: 3600000
          example: 120000
        width:
          type: integer
          description: Input width in pixels (for credit estimation)
          example: 1920
        height:
          type: integer
          description: Input height in pixels (for credit estimation)
          example: 1080
    JobCreated:
      type: object
      required:
      - id
      - status
      - tool
      - creditsReserved
      - estimatedCredits
      - poll
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - queued
          - pending_upload
          description: '`queued` for URL inputs, `pending_upload` for file uploads'
        tool:
          type: string
        creditsReserved:
          type: integer
          description: Always 0 — nothing is held when a job is created
        estimatedCredits:
          type: integer
          description: What the AI result should cost, charged when it's ready (0 for non-AI tools, which are included in the plan)
        uploads:
          type: array
          nullable: true
          description: Presigned upload URLs (only for file upload jobs). PUT your file to each URL within 30 minutes.
          items:
            type: object
            required:
            - name
            - url
            properties:
              name:
                type: string
                description: Filename this upload corresponds to
              url:
                type: string
                format: uri
                description: Presigned PUT URL (expires in 30 minutes)
        poll:
          type: string
          description: Convenience path for polling this job
          example: /api/v1/jobs/d290f1ee-6c54-4b01-90e6-d701748f0851
    LockedJob:
      description: A completed job whose result is locked — the job, with `outputUrl` null, plus what the download needs
      allOf:
      - $ref: '#/components/schemas/Job'
      - $ref: '#/components/schemas/Error'
    Metrics:
      type: object
      properties:
        wallTimeMs:
          type: integer
          description: Total wall-clock execution time in milliseconds
        cpuTimeMs:
          type: integer
          description: CPU time in milliseconds
        peakMemoryBytes:
          type: integer
          description: Peak memory usage in bytes
        estimatedCostMicroUsd:
          type: integer
          description: Estimated container cost in micro-USD
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        code:
          type: string
          enum:
          - plan_required
          - insufficient_credits
          description: Machine-readable reason (on 402 and plan 403 responses)
        required:
          type: integer
          nullable: true
          description: Credits required (on 402 responses; null when a plan is what's missing)
        balance:
          type: integer
          description: Current balance (on 402 responses)
        why:
          type: string
          enum:
          - daily-limit
          - too-long
          - too-large
          description: With plan_required on a finished job — why a free account can't download it
        plan:
          type: string
          description: The account's plan (on plan_required 403 responses)
        pricing:
          type: string
          format: uri
          description: Where to get a plan or credits
        tools:
          type: string
          description: Hint for discovering tools (on unknown tool errors)
    Job:
      type: object
      required:
      - id
      - status
      - tool
      - progress
      - creditsReserved
      - createdAt
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - pending_upload
          - queued
          - processing
          - completed
          - failed
          - cancelled
        tool:
          type: string
        progress:
          type: integer
          minimum: 0
          maximum: 100
          description: Processing progress percentage
        progressMessage:
          type: string
          nullable: true
          description: Human-readable progress update (e.g. "Encoding...")
        errorMessage:
          type: string
          nullable: true
          description: Error description (only when status is `failed`)
        creditsReserved:
          type: integer
          description: Always 0 — nothing is held when a job is created
        creditsCharged:
          type: integer
          nullable: true
          description: AI credits charged for the result (0 for non-AI tools)
        createdAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
          nullable: true
        outputUrl:
          type: string
          format: uri
          nullable: true
          description: Presigned R2 download URL (completed and unlocked jobs, valid 1 hour); null while a completed result is locked
        outputFilename:
          type: string
          nullable: true
          description: Suggested filename for the output
        outputSize:
          type: integer
          nullable: true
          description: Output file size in bytes
        metrics:
          allOf:
          - $ref: '#/components/schemas/Metrics'
          nullable: true
          description: Processing metrics (only after completion, may be null)
  responses:
    RateLimited:
      description: Rate limit exceeded (per key — 100 requests/minute on Lite, 200 on Pro, 600 on Business)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Rate limit exceeded
    PlanRequired:
      description: The key's account has no paid plan (Lite or higher)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: API keys need a paid plan (Lite or higher)
            code: plan_required
            plan: Free
            pricing: https://editclips.online/pricing
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Invalid API key
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'API key with `ec_live_` prefix. Create keys under [Dashboard → Developer](https://editclips.online/dashboard/developer) (paid plans).

        '
x-refined-from:
- editclips-online-openapi.yaml
- openapi.yaml