ffpipe Discovery API

openapi: 3.2.0
info:
  title: ffpipe — media processing for agents, by VidDay Discovery…
  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: Discovery
  description: Unpaid, cacheable descriptions of this service.
paths:
  /health:
    get:
      operationId: health
      security: []
      tags:
      - Discovery
      summary: Liveness (free)
      responses:
        '200':
          description: The gateway is up.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  service:
                    type: string
                required:
                - ok
                - service
              example:
                ok: true
                service: ffpipe-gateway
  /:
    get:
      operationId: landing
      security: []
      tags:
      - Discovery
      summary: Human landing page (free)
      responses:
        '200':
          description: Self-contained HTML overview.
          content:
            text/html:
              schema:
                type: string
  /.well-known/x402:
    get:
      operationId: wellKnownX402
      security: []
      tags:
      - Discovery
      summary: x402 discovery manifest (free)
      description: Machine-readable list of this gateway's paid resources with prices and payment requirements — the same information the 402 challenges carry, in the de-facto well-known manifest shape crawlers fetch.
      responses:
        '200':
          description: Discovery manifest.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /llms.txt:
    get:
      operationId: llmsTxt
      security: []
      tags:
      - Discovery
      summary: Agent primer (free)
      description: 'Plain-text orientation for LLM agents: endpoints, prices, the handshake, ready-to-run snippets.'
      responses:
        '200':
          description: Plain text.
          content:
            text/plain:
              schema:
                type: string
  /openapi.json:
    get:
      operationId: openapi
      security: []
      tags:
      - Discovery
      summary: This document (free)
      responses:
        '200':
          description: OpenAPI 3.1 document.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /privacy:
    get:
      operationId: privacy
      security: []
      tags:
      - Discovery
      summary: Privacy policy (free)
      responses:
        '200':
          description: The privacy policy, as HTML — includes what the public blockchain necessarily exposes about payments.
          content:
            text/html:
              schema:
                type: string
  /terms:
    get:
      operationId: terms
      security: []
      tags:
      - Discovery
      summary: Terms of service (free)
      responses:
        '200':
          description: The terms of service, as HTML.
          content:
            text/html:
              schema:
                type: string
components:
  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