ClipOnIt Agents API

openapi: 3.2.0
info:
  title: Cliponit App Agents API
  version: 1.0.0
  contact:
    name: ClipOnIt
    url: https://cliponit.app
  license:
    name: Proprietary
    url: https://cliponit.app
  description: 'Operations tagged agents across 2 of this provider''s published API definitions: cliponit-app-openapi.json, cliponit-app-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://cliponit.app
  description: Production
- url: http://localhost:3000
  description: Local dev (cargo run)
security:
- ApiKey: []
- SessionCookie: []
- OAuth2:
  - clips
tags:
- name: Agents
  description: 'Autonomous production: one call composes, checks and renders a video; jobs, live progress, templates.'
paths:
  /api/agent/produce:
    post:
      tags:
      - Agents
      operationId: agentProduce
      summary: Produce an explainer video end to end (no human)
      description: 'Exactly one source: `topic` (the server''s Claude writes the script), `script`, `audio_id` or `audio_url` (the user''s own voice-over), or `scenes`. Runs transcribe → compose → check → render in the background; poll `getJob` (or `GET /api/jobs/{id}/events`, SSE) until `done` (`url`, `editor_url`) or `failed`. 402 = monthly explainer renders or monthly AI budget reached, 403 = plan or read-only API key, 429 = 2 jobs already running.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                topic:
                  type: string
                script:
                  $ref: '#/components/schemas/ExplainerScript'
                audio_id:
                  type: string
                audio_url:
                  type: string
                scenes:
                  type: array
                  items:
                    type: object
                style:
                  type: string
                  enum:
                  - pixel-news
                  - archibald
                duration_s:
                  type: integer
                  minimum: 15
                  maximum: 180
                voice:
                  type: string
                  description: 'ElevenLabs voice of the catalogue (templates/voices.json), by voice_id or name: N6vE6dp4ouYqQlMCBL5j Guillaume (fr), J50pwizkkVglhJNh30K8 Aslan (fr), jfEwztGDkpbpy89xeku6 Cyp (fr), TojRWZatQyy9dujEdiQ1 Koraly (fr), O31r762Gb3WFygrEOGh0 Victoire (fr), 5OnMHwgTFgvPVwE8jP6B Anaïs (fr), nPczCjzI2devNBz1zQrb Brian (en), TX3LPaxmHKxFdv7VOQHJ Liam (en), pFZP5JQG7iQjIQuC4Bku Lily (en), cgSgspJ2msm6clMCkdW9 Jessica (en). Old OpenAI names (alloy, ash, nova, onyx…) still accepted, rendered with OpenAI. Other value → 400.'
                brand:
                  type: boolean
                title:
                  type: string
      responses:
        '202':
          description: 'Accepted: the job runs in the background'
          content:
            application/json:
              schema:
                type: object
                properties:
                  job:
                    $ref: '#/components/schemas/AgentJob'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          description: 'Two productions already running: retry later'
    servers:
    - url: https://cliponit.app
      description: Production
    - url: http://localhost:3000
      description: Local dev (cargo run)
  /api/jobs:
    get:
      tags:
      - Agents
      operationId: listJobs
      summary: List agent production jobs
      parameters:
      - name: active
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
        description: 1 = only queued/running
      responses:
        '200':
          description: Jobs, newest first
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentJob'
    servers:
    - url: https://cliponit.app
      description: Production
    - url: http://localhost:3000
      description: Local dev (cargo run)
  /api/jobs/{id}:
    get:
      tags:
      - Agents
      operationId: getJob
      summary: Get an agent production job
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentJob'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://cliponit.app
      description: Production
    - url: http://localhost:3000
      description: Local dev (cargo run)
  /api/jobs/{id}/cancel:
    post:
      tags:
      - Agents
      operationId: cancelJob
      summary: Cancel a queued or running job
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Job with status canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentJob'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://cliponit.app
      description: Production
    - url: http://localhost:3000
      description: Local dev (cargo run)
  /api/jobs/{id}/events:
    get:
      tags:
      - Agents
      operationId: jobEvents
      summary: Live job progress (Server-Sent Events)
      description: '`text/event-stream`: one event per step / percent change (the JOB as data), closed when the job ends.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: SSE stream
          content:
            text/event-stream:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://cliponit.app
      description: Production
    - url: http://localhost:3000
      description: Local dev (cargo run)
  /api/explainer/my-templates:
    get:
      tags:
      - Agents
      operationId: listMyTemplates
      summary: List the account's parameterized script templates
      responses:
        '200':
          description: Templates
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
    post:
      tags:
      - Agents
      operationId: saveMyTemplate
      summary: Save a script as a parameterized template ({{sujet}}, {{chiffre}}…)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - script
              properties:
                name:
                  type: string
                description:
                  type: string
                script:
                  $ref: '#/components/schemas/ExplainerScript'
      responses:
        '200':
          description: Stored template
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
    servers:
    - url: https://cliponit.app
      description: Production
    - url: http://localhost:3000
      description: Local dev (cargo run)
  /api/explainer/my-templates/{id}/instantiate:
    post:
      tags:
      - Agents
      operationId: instantiateMyTemplate
      summary: Fill a template's params and return the script (nothing rendered)
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - values
              properties:
                values:
                  type: object
      responses:
        '200':
          description: '{script}'
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://cliponit.app
      description: Production
    - url: http://localhost:3000
      description: Local dev (cargo run)
  /api/explainer/my-templates/{id}/run:
    post:
      tags:
      - Agents
      operationId: runMyTemplate
      summary: Produce a video from a template (fixed or recompose)
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - values
              properties:
                values:
                  type: object
                mode:
                  type: string
                  enum:
                  - fixed
                  - recompose
                style:
                  type: string
                voice:
                  type: string
                  description: 'ElevenLabs voice of the catalogue (templates/voices.json), by voice_id or name: N6vE6dp4ouYqQlMCBL5j Guillaume (fr), J50pwizkkVglhJNh30K8 Aslan (fr), jfEwztGDkpbpy89xeku6 Cyp (fr), TojRWZatQyy9dujEdiQ1 Koraly (fr), O31r762Gb3WFygrEOGh0 Victoire (fr), 5OnMHwgTFgvPVwE8jP6B Anaïs (fr), nPczCjzI2devNBz1zQrb Brian (en), TX3LPaxmHKxFdv7VOQHJ Liam (en), pFZP5JQG7iQjIQuC4Bku Lily (en), cgSgspJ2msm6clMCkdW9 Jessica (en). Old OpenAI names (alloy, ash, nova, onyx…) still accepted, rendered with OpenAI. Other value → 400.'
                brand:
                  type: boolean
                duration_s:
                  type: integer
                  minimum: 15
                  maximum: 180
      responses:
        '202':
          description: 'Accepted: the job runs in the background'
          content:
            application/json:
              schema:
                type: object
                properties:
                  job:
                    $ref: '#/components/schemas/AgentJob'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          description: 'Two productions already running: retry later'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://cliponit.app
      description: Production
    - url: http://localhost:3000
      description: Local dev (cargo run)
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable message (French or English)
    ExplainerScript:
      type: object
      description: 'Explainer script `{title, box, theme?, voice, cast?, gap?, subscribe_text?, scenes:[{say, date, credit, stamp?, camera?, elements:[{el, x, y, in, anim, loop, out, exit, k, color?, tint?, who?, scale?, anchor?, zoom?, …}]}]}` (see docs/explainer.md §1). `in`/`out`: seconds or `{word, occurrence?=1, offset?=0, edge?: "end"}` (instant that word of the scene''s `say` is spoken, from the real voice timing). `cast` `{id: {hair, hair_color, beard, glasses, outfit, colors, party, label…}}` merged under any element with `who: id` (element wins). `scale` 0.25..6, `anchor` center|bottom, `zoom` `{to, at:[t0,t1], x?, y?}`; scene `camera.target` = element index. `gap` = silence between scenes (s, default 0.3, 0..2; 0 with an imported audio). `subscribe_text` = end-screen slogan ("" = none). `voice` = `{voice_id, model?, style?: 0..1 expressiveness, speed?: 0.5..2}` (ElevenLabs; catalogue and defaults in `GET /api/explainer/schema`, `voice.voice_id`); an old OpenAI voice `{model, voice, instructions}` still renders with OpenAI.'
      additionalProperties: true
    AgentJob:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - queued
          - running
          - done
          - failed
          - canceled
        step:
          type: string
          enum:
          - queued
          - transcribe
          - compose
          - check
          - render
          - done
        step_label:
          type: string
        step_label_en:
          type: string
        progress:
          type: number
        percent:
          type: integer
        message:
          type: string
        source:
          type: string
        title:
          type: string
        agent:
          type: string
        explainer_id:
          type: string
        doc:
          type: string
        url:
          type: string
        editor_url:
          type: string
        error:
          type: string
        cost_usd:
          type: number
  responses:
    BadRequest:
      description: 'Validation error — the message names the field, e.g. `champ subtitles.size invalide : attendu 1..3`'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: Plan quota reached (monthly videos, daily searches, file size/duration on free)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'Quota mensuel atteint : passe au plan supérieur'
    Forbidden:
      description: Feature not included in the user's plan (upgrade at /billing)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: L'API & MCP nécessitent le plan Starter
    NotFound:
      description: Resource not found or not owned by the user
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: clip 6f1c2d6e-… introuvable (ou n'appartient pas à ce compte)
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: ck_<64 hex>
      description: 'Personal API key from `POST /api/me/api-key` (Starter plan and above). Also accepted: the session `token` returned by `login`/`register`. Send `Authorization: Bearer ck_…`.'
    SessionCookie:
      type: apiKey
      in: cookie
      name: session
      description: HttpOnly cookie set by `register`/`login` (browser clients).
    OAuth2:
      type: oauth2
      description: 'OAuth 2.1 for MCP connectors (Claude.ai / Claude Desktop / Claude Code / ChatGPT): discovery at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`, dynamic client registration (RFC 7591) at `/oauth/register`, PKCE S256 required, public clients only. Access tokens (`cko_…`, 1 h) are accepted everywhere a `ck_…` key is; refresh tokens (`ckr_…`, 90 days) rotate on use.'
      flows:
        authorizationCode:
          authorizationUrl: https://cliponit.app/oauth/authorize
          tokenUrl: https://cliponit.app/oauth/token
          refreshUrl: https://cliponit.app/oauth/token
          scopes:
            clips: Import videos, read/edit clips, run exports (everything the API key allows)
externalDocs:
  description: Agent guide (llms-api.txt)
  url: https://cliponit.app/llms-api.txt
x-refined-from:
- cliponit-app-openapi.json
- cliponit-app-openapi.yml