ffpipe MCP API

openapi: 3.2.0
info:
  title: ffpipe — media processing for agents, by VidDay MCP 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: MCP
  description: The same job API as MCP tools (Model Context Protocol, streamable HTTP). JSON-RPC, so the operation below is a pointer, not a full description — connect an MCP client and list the tools.
paths:
  /mcp:
    post:
      operationId: mcp
      security: []
      tags:
      - MCP
      summary: MCP server — convert_video / probe_media / extract_frames / get_job_status /…
      description: 'Remote MCP server (streamable HTTP transport, stateless — no session id issued or required; responses are plain JSON). Tools: `convert_video` (paid, same terms as POST /v1/convert), `probe_media` (paid, same terms as POST /v1/probe), `extract_frames` (paid, same terms as POST /v1/frames), `get_job_status` (free, same token semantics as GET /v1/jobs/{id}), `get_balance` (free, no input — the connected account''s balance, same body as GET /v1/credits/balance; anonymous callers get an `unauthorized` tool result), `leave_feedback` (free, same body as POST /v1/feedback). The last three are registered under every configuration. Every tool carries MCP annotations: the paid job tools are writes (`readOnlyHint: false`, and never idempotent — two identical calls are two jobs and two charges), the free lookups are read-only, and `probe_media` reports `readOnlyHint: true` (it inspects a file and leaves no artifact behind). Nothing here is `destructiveHint: true`. Payment rides the MCP protocol (Cloudflare Agents SDK x402 convention), NOT HTTP headers: an unpaid paid-tool call returns an `isError` result whose `_meta["x402/error"]` carries the same `accepts[]` as a REST 402; the client signs and retries the call with `_meta["x402/payment"]` set to the base64 payload. `withX402Client` from the `agents` npm package automates this. Capture semantics are identical to REST: verify before the tool runs, settle only on a non-error result. Retry vouchers are redeemed via the optional `retryVoucher` tool input. The body is JSON-RPC 2.0 per the MCP spec — not usefully describable as an OpenAPI schema; connect an MCP client and call tools/list.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: A JSON-RPC 2.0 MCP message (initialize, tools/list, tools/call, …).
      responses:
        '200':
          description: JSON-RPC response. Tool-level failures (including the x402 payment challenge) are `isError` tool results inside a 200, per MCP.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
      x-x402:
        transport: mcp
        challenge: _meta["x402/error"]
        payment: _meta["x402/payment"]
        settlement: _meta["x402/payment-response"]
        tools:
          convert_video:
            price: $0.02
            priceUSD: 0.02
            amountAtomic: '20000'
          probe_media:
            price: $0.01
            priceUSD: 0.01
            amountAtomic: '10000'
          extract_frames:
            price: $0.01
            priceUSD: 0.01
            amountAtomic: '10000'
          get_job_status:
            price: free
          get_balance:
            price: free
          leave_feedback:
            price: free
        capture: verify before the tool callback, settle only after a non-error tool result — failed tool calls are never charged
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