CueFrame Resources API

openapi: 3.2.0
info:
  title: Cueframe Ai Resources API
  version: v1
  contact:
    name: CueFrame
    url: https://cueframe.ai
    email: support@cueframe.ai
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  description: 'Operations tagged resources across 2 of this provider''s published API definitions: cueframe-ai-openapi.json, cueframe-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.cueframe.ai
  description: Production
tags:
- name: Resources
paths:
  /v1/resources/search:
    post:
      operationId: searchResources
      tags:
      - Resources
      summary: Search stock media (Pexels / Pixabay / Freesound / Klipy)
      description: Search licensed stock media by keyword. Pass `query` for one search, or `queries[]` (≤10) to run a batch in ONE call — the batch returns `results[]`, one entry per query in order, each with its own `candidates` (and an `error` string if that single query failed; one bad query never discards the rest). `kind` selects the corpus (video/photo default to Pexels; Pixabay is explicitly selectable; sfx → Freesound CC0-only; gif → Klipy); defaults to video. Returns ranked candidates each carrying an opaque `candidateId` — pass it to import_resource to bring the asset into a project. Free + rate-limited; results are cached for 7 days, after which a candidateId must be refreshed by searching again. For sfx, bound the result by clip length with `durationSec` — impacts/ticks ≈ 0–2s, risers/whooshes ≈ 2–8s, ambients unbounded. For video, use minWidth/minHeight to exclude smaller renditions.
      security:
      - bearerAuth: []
      - oauth2:
        - media:read
      - x402: []
      x-permissions:
        media:
        - read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResourceSearchRequest'
      responses:
        '200':
          description: Ranked stock candidates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceSearchResponse'
        '400':
          description: Bad request — validation_error / invalid_cursor / invalid_query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid Authorization header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '402':
          description: 'Payment required. Returned when the caller presents no API key on a priced operation: the body AND the `Payment-Required` header carry the x402 v2 challenge (accepted scheme, network, USDC asset, amount, payTo). Sign the EIP-3009 authorization and retry with a `PAYMENT-SIGNATURE` header. A KEYED caller sees this status instead when their plan lacks or has exhausted the feature (`billing_required`).'
          headers:
            Payment-Required:
              description: Base64 x402 v2 PaymentRequired envelope — the same challenge as the body, for clients that read it off the header.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/X402PaymentRequired'
        '403':
          description: Forbidden — permission insufficient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. Retry-After header present.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Service unavailable — billing_unavailable / honest-503 for runtime deps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
        protocols:
        - x402: {}
    servers:
    - url: https://api.cueframe.ai
      description: Production
  /v1/resources/import:
    post:
      operationId: importResource
      tags:
      - Resources
      summary: Import a stock candidate or a curated SFX-pack sound
      description: 'Two lanes. STOCK { projectId, candidateId }: import a candidate returned by search_resources into a project as an org-owned media item (preserving provider/externalId/license provenance; bytes deduped across orgs). Async: returns { id, status:''importing'' }; status flips to complete when the import finishes (poll GET /media/:id). A candidate whose 7-day search cache has expired returns 422 — re-search. PACK { kind:"sfx-pack", id: }: mint/return the org media item for a curated CC0 SFX-pack sound (soundId from list_catalog''s sfx[]) — returns { id, status:''ready'' } immediately to place as a normal sfx clip. Idempotent per (org, soundId); an unknown soundId is a 422. Pack imports are FREE: no plan feature required, and an x402 payment is released unsettled (no charge). PRICE of a stock import for a keyed (API-key / session) caller: 0 credits — the resource_import entitlement is a plan grant, not a meter (get_account reports `entitlements.resource_import.listUsdPerUnit: 0`); the imported bytes count toward the `storage` gauge. Only an unkeyed x402 caller pays the $0.01 import tier.'
      security:
      - bearerAuth: []
      - oauth2:
        - media:write
      - x402: []
      x-permissions:
        media:
        - write
      x-x402: import
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResourceImportRequest'
      responses:
        '201':
          description: Import reserved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceImportResponse'
        '400':
          description: Bad request — validation_error / invalid_cursor / invalid_query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing or invalid Authorization header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '402':
          description: Payment required — billing_required or x402 payment_*.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Forbidden — permission insufficient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: Unprocessable — invalid_composition / media_in_use / session_in_use / render_not_cancellable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. Retry-After header present.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Service unavailable — billing_unavailable / honest-503 for runtime deps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.01'
        protocols:
        - x402: {}
    servers:
    - url: https://api.cueframe.ai
      description: Production
components:
  schemas:
    ResourceSearchResponse:
      type: object
      properties:
        provider:
          type: string
          enum:
          - pexels
          - pixabay
          - freesound
          - klipy
        kind:
          type: string
          enum:
          - video
          - photo
          - sfx
          - gif
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/ResourceCandidate'
        results:
          type: array
          items:
            $ref: '#/components/schemas/ResourceSearchResult'
      additionalProperties: false
      description: POST /resources/search response — `candidates` for one query, `results[]` for a batch.
    ResourceImportResponse:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - importing
          - ready
      required:
      - id
      - status
      additionalProperties: false
      description: POST /resources/import response.
    ResourceImportRequest:
      type: object
      properties:
        kind:
          type: string
          enum:
          - sfx-pack
          - music-pack
        id:
          type: string
          minLength: 1
        projectId:
          type: string
          minLength: 1
        candidateId:
          type: string
          minLength: 1
      additionalProperties: false
      description: POST /resources/import body — stock candidate lane { projectId, candidateId } OR curated pack lane { kind:"sfx-pack"|"music-pack", id }.
      example:
        projectId: abcdefghij1234567890abcdef123456
        candidateId: cand_01J8Z3K9Q2X4Y5W6V7T8R9S0P1
    ResourceSearchRequest:
      type: object
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 200
        queries:
          minItems: 1
          maxItems: 10
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 200
        kind:
          type: string
          enum:
          - video
          - photo
          - sfx
          - gif
        provider:
          type: string
          enum:
          - pexels
          - pixabay
          - freesound
          - klipy
        limit:
          type: integer
          exclusiveMinimum: 0
          maximum: 50
        minWidth:
          description: Video-only minimum selected-rendition width in pixels; smaller results are excluded.
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        minHeight:
          description: Video-only minimum selected-rendition height in pixels; smaller results are excluded.
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        durationSec:
          type: object
          properties:
            min:
              type: number
              minimum: 0
            max:
              type: number
              exclusiveMinimum: 0
          additionalProperties: false
          description: sfx-only clip-length bound in seconds → Freesound native filter.
      additionalProperties: false
      description: POST /resources/search body — one `query`, or a batch of `queries[]`.
    ResourceSearchResult:
      type: object
      properties:
        query:
          type: string
        provider:
          type: string
          enum:
          - pexels
          - pixabay
          - freesound
          - klipy
        kind:
          type: string
          enum:
          - video
          - photo
          - sfx
          - gif
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/ResourceCandidate'
        error:
          type: string
      required:
      - query
      - candidates
      additionalProperties: false
      description: One query's candidates within a batch search.
    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Stable machine-readable error code per §Error Model.
            message:
              type: string
              description: Human-readable message.
            contract:
              type: string
              description: Contract version that produced this verdict. If it differs between two calls, the rules changed underneath you, not your request.
            contractVersion:
              type: string
              description: 'Version of the published `@cueframe/api-contract` this server implements. Compare it with the `contractVersion` of the package your client was generated from: a higher value here means the server has moved ahead of your document.'
            details:
              description: Optional context (currentEtag, projectIds, retryAfter, …).
              type: object
              propertyNames:
                type: string
              additionalProperties: {}
          required:
          - code
          - message
          - contract
          - contractVersion
          description: Standard API error envelope.
      required:
      - error
      description: Error envelope used by every non-2xx response.
    ResourceCandidate:
      type: object
      properties:
        candidateId:
          type: string
        provider:
          type: string
          enum:
          - pexels
          - pixabay
          - freesound
          - klipy
        kind:
          type: string
          enum:
          - video
          - photo
          - sfx
          - gif
        thumbnail:
          type: string
        previewUrl:
          type: string
        downloadUrl:
          type: string
        duration:
          type: number
        width:
          type: number
        height:
          type: number
        author:
          type: string
        authorUrl:
          type: string
        assetUrl:
          type: string
        license:
          type: string
      required:
      - candidateId
      - provider
      - kind
      - thumbnail
      - previewUrl
      - author
      additionalProperties: false
      description: A stock resource search candidate.
    X402PaymentRequired:
      type: object
      title: X402PaymentRequired
      description: x402 v2 PaymentRequired challenge — the body of a 402 on a priced operation.
      properties:
        x402Version:
          type: integer
          const: 2
        accepts:
          type: array
          description: Accepted payment requirements. Read `accepts[0]` for scheme (`exact` for a fixed price, `upto` for a measured one), network (CAIP-2), asset, amount and payTo.
          items:
            type: object
        error:
          type: string
          description: Human-readable reason.
      required:
      - x402Version
      - accepts
  securitySchemes:
    oauth2:
      type: oauth2
      description: Authorization code with PKCE (S256). Request explicit resource scopes for least privilege; identity-only grants retain account-level access.
      flows:
        authorizationCode:
          authorizationUrl: https://api.cueframe.ai/api/auth/mcp/authorize
          tokenUrl: https://api.cueframe.ai/api/auth/mcp/token
          scopes:
            media:read: Read media
            media:write: Modify media
            sessions:read: Read sessions
            sessions:write: Modify sessions
            projects:read: Read projects
            projects:write: Modify projects
            renders:read: Read renders
            renders:write: Modify renders
            webhooks:read: Read webhooks
            webhooks:write: Modify webhooks
            billing:read: Read billing
            billing:write: Modify billing
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: cf_live_* or cf_test_*
      description: API key auth. Prefix `cf_live_` for production orgs, `cf_test_` for sandbox.
    x402:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: x402 v2 payment header (EIP-3009 USDC on Base; base64 PaymentPayload). Returned 402 Payment-Required if absent on priced endpoints.
x-refined-from:
- cueframe-ai-openapi.json
- cueframe-ai-openapi.yml