ffpipe Feedback API

openapi: 3.2.0
info:
  title: ffpipe — media processing for agents, by VidDay Feedback API
  version: 0.1.0
  summary: Machine-payable video conversion, media inspection and frame extraction, priced per job in USDC over x402.
  description: 'ffpipe does video conversion, media inspection and frame extraction for callers that pay per request with x402 — no account, no API key, no invoice.


    **Live on base mainnet.** Payments settle in real USDC (eip155:8453).


    Flow: POST a paid endpoint without payment → `402` with a `PAYMENT-REQUIRED` challenge → an x402 client signs and retries → `202 { jobId, statusUrl }` → poll `statusUrl` (free, token-gated) until `finished` or `error`.


    Prefer tools over REST? The same API is served as a remote MCP server at `/mcp` (streamable HTTP) — see that path''s description.


    Jobs are asynchronous. Download results within 24 hours of completion.


    If a paid job fails inside our pipeline, or could not be queued after your payment settled, its status response carries a `retryVoucher` — one free retry, chained up to 3 times per job lineage. That is the refund mechanism; there are no on-chain refunds.


    Caveat for `sourceUrl`: we fetch it from datacenter IP ranges, so origins that block datacenter egress (some CDNs answer 403) fail with `ingest_failed`. Prefer a presigned URL from storage you control.


    Need an operation that is not here? Today we offer video conversion, media inspection and frame extraction — `POST /v1/feedback` (free) is where to ask for anything else, and those requests are what drive the roadmap.'
  contact:
    name: VidDay
    url: https://www.vidday.com
    email: ffpipe@vidday.com
  x-guidance: 'To convert a video: POST https://ffpipe.dev/v1/convert with JSON {"sourceUrl": "<public https URL>"} — or {"upload": true} to receive an uploadUrl you PUT the raw bytes to (≤ 100 MiB either way). The first, unpaid request answers 402 with a PAYMENT-REQUIRED challenge ($0.02 USDC on base); sign it with any x402 client and repeat the request. The 202 response carries a statusUrl — poll it (free) until status is finished, then download the MP4 from resultUrl within 24 hours. If the job fails on our side, the status response includes a retryVoucher header value good for one free retry. Anything you wanted but did not find is worth a free POST /v1/feedback — capability requests drive what gets built next.'
  termsOfService: https://ffpipe.dev/terms
servers:
- url: https://ffpipe.dev
  description: this gateway
tags:
- name: Feedback
  description: Free, one-way channel for capability requests, bug reports and feedback. Requests for operations ffpipe does not offer yet are aggregated and drive what gets built next.
paths:
  /v1/feedback:
    post:
      operationId: leaveFeedback
      security: []
      tags:
      - Feedback
      summary: Request a capability, report a bug, or send feedback (free)
      description: 'Free, unauthenticated and one-way. ffpipe offers video conversion, media inspection and frame extraction and nothing else today — if the operation you needed is not here (another output format, a trimmed clip, a different transformation), this is where to say so. Submissions are aggregated and are the primary input to what gets built next, so one concrete sentence is worth more than none. Only `message` is required, and the intake is deliberately forgiving: it is also read from `feedback`, `text`, `comment` or `body`, or from a raw `text/plain` request body. `type` is optional and defaults to `feedback`; `jobId` is optional CONTEXT and is deliberately not verified (no token, no ownership check, and it cannot be used to probe whether a job exists); `contact` is optional and is the only way we can reply. Answers `202 { ok: true }` — accepted for processing. No id is issued and there is no read-back endpoint. No payment is involved: this route has no 402 and cannot queue work.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackRequest'
            example:
              type: feature_request
              message: I needed a single frame as a JPEG at a given timestamp, not a full conversion.
              contact: agent-owner@example.com
          text/plain:
            schema:
              type: string
              maxLength: 2000
              description: The message on its own. Filed as `feedback` with no `jobId` or `contact`.
            example: I needed a single frame as a JPEG at a given timestamp, not a full conversion.
      responses:
        '202':
          description: Accepted. Recorded and counted; nothing further happens synchronously.
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                properties:
                  ok:
                    type: boolean
                    const: true
              example:
                ok: true
        '400':
          description: Malformed JSON, unknown `type`, missing/empty `message` (under any of its accepted keys), or a field over its length limit. The `message` restates the shape we accept, so a caller can correct itself from the refusal alone.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: invalid_request
                  message: …
          x-error-codes:
          - invalid_request
        '429':
          description: Over the per-IP submission rate (5/minute) or the per-IP daily acceptance cap (50/day). Retry per `retry-after`.
          headers:
            retry-after:
              description: Seconds to wait before retrying.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: rate_limited
                  message: …
          x-error-codes:
          - rate_limited
          - daily_cap_exceeded
        '503':
          description: The submission could not be recorded, so it was NOT accepted — please retry rather than assume we have it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: unavailable
                  message: …
          x-error-codes:
          - unavailable
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - invalid_request
              - invalid_source_url
              - source_too_large
              - ingest_failed
              - pipeline_error
              - rate_limited
              - daily_cap_exceeded
              - not_found
              - literal_path_template
              - gone
              - unknown_job
              - unauthorized
              - not_configured
              - unavailable
            message:
              type: string
    FeedbackRequest:
      type: object
      required:
      - message
      additionalProperties: true
      description: Unknown properties are ignored. Nothing here is authenticated and nothing is charged.
      properties:
        type:
          type: string
          enum:
          - feature_request
          - bug
          - feedback
          default: feedback
          description: '`feature_request` for an operation ffpipe does not offer yet (the one this channel exists for), `bug` for something broken, `feedback` for anything else. Optional — omitted means `feedback`; a value outside this list is refused rather than guessed.'
        message:
          type: string
          minLength: 1
          maxLength: 2000
          description: What you needed, what broke, or what you think. Plain text, trimmed; be concrete about the operation you wanted. Also accepted under `feedback`, `text`, `comment`, `body` — or as a raw `text/plain` body.
        jobId:
          type: string
          maxLength: 200
          description: 'Optional job this relates to. CONTEXT ONLY: it is not verified, needs no token, and reveals nothing about whether that job exists.'
        contact:
          type: string
          maxLength: 200
          description: Optional email or handle to reply at. Omit for an anonymous submission.
  securitySchemes:
    x402:
      type: apiKey
      in: header
      name: payment-signature
      description: 'Not an API key: an x402 v2 payment payload, freshly signed per request from the PAYMENT-REQUIRED challenge. Modelled as apiKey because OpenAPI has no x402 security type — see the `x-x402` extensions.'
    retryVoucher:
      type: apiKey
      in: header
      name: x-retry-voucher
      description: Single-use retry credential issued when a paid job failed on our side.
x-x402:
  protocol: x402
  version: 2
  network: eip155:8453
  networkName: base
  scheme: exact
  asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
  assetSymbol: USDC
  assetDecimals: 6
  facilitator: https://api.cdp.coinbase.com/platform/v2/x402
  payTo: '0x38c72cAb5d8F053a7CCE4F522b923C3c70291B9d'
  testnet: false
  prices:
    POST /v1/convert: $0.02
    POST /v1/probe: $0.01
    POST /v1/frames: $0.01
  challengeHeader: PAYMENT-REQUIRED
  paymentHeader: payment-signature
  settlementHeader: PAYMENT-RESPONSE
  capture: verify before the handler, settle after a 2xx — non-2xx responses are never charged