# Weftly API

> AI post-production for audio and video. Transcribe, summarize, find compelling clips, and cut horizontal or 9:16 vertical clips. Pay per job — no account required. This file lives at the API origin (https://api.weftly.ai); a richer human-facing version is at https://weftly.ai/llms.txt.

## Service

- **API base:** https://api.weftly.ai/api/v1
- **MCP endpoint:** https://api.weftly.ai/mcp (Streamable HTTP, JSON-RPC 2.0, protocol version 2025-03-26)
- **OpenAPI spec:** https://api.weftly.ai/openapi.json (mirror: https://api.weftly.ai/.well-known/openapi.json)
- **MPP discovery:** https://api.weftly.ai/.well-known/mpp.json
- **Agent card (A2A):** https://api.weftly.ai/.well-known/agent-card.json
- **AI plugin manifest:** https://api.weftly.ai/.well-known/ai-plugin.json
- **MCP server card:** https://api.weftly.ai/.well-known/mcp/server-card.json
- **API catalog:** https://api.weftly.ai/.well-known/api-catalog.json
- **MPP smoke test ($0.01):** https://api.weftly.ai/api/test
- **Health check:** https://api.weftly.ai/health
- **Marketing site:** https://weftly.ai
- **Browser chat:** https://chat.weftly.ai

## Pricing

| Job type | Price | Notes |
|---|---:|---|
| transcribe (audio) | $0.50 | SRT + word-level JSON |
| transcribe (video) | $1.00 | SRT + word-level JSON |
| summarize (audio) | $0.75 | Includes free transcript |
| summarize (video) | $1.25 | Includes free transcript |
| find_clips (video) | $2.00 | Ranked clip candidates + free transcript |
| extract_clip | $0.50 | Cut horizontal .mp4 from a parent video job |
| extract_vertical_clip | $0.50 | Cut 9:16 .mp4 from a parent video job (TikTok / Reels / Shorts) |
| publish_youtube | $1.75 | Publish to YouTube with captions — app pending YouTube verification |
| MPP smoke test | $0.01 | Verifies MPP plumbing |

Authoritative price table at https://api.weftly.ai/.well-known/mpp.json. Failed jobs auto-refund.

## Payment rails

1. **Stripe SPT** — card payments via hosted Stripe Checkout. For browser users and MCP hosts without a wallet.
2. **Tempo USDC (MPP)** — crypto rails for autonomous flows. Sign `WWW-Authenticate: Payment …` challenges with [mppx](https://github.com/wevm/mppx).

Both use the Machine Payments Protocol (MPP, [paymentauth.org](https://paymentauth.org)). Discovery at `/.well-known/mpp.json` and per-operation `x-payment-info` in `/openapi.json`.

## Two flow shapes

### Upload-based — `transcribe`, `summarize`, `find_clips`

1. `POST /api/v1/sessions` → session token (free).
2. `POST /api/v1/jobs` with `{job_type, filename, content_type}` and `Authorization: Bearer <token>`. Response carries Stripe checkout URL and/or MPP deposit info.
3. Pay via Stripe (`checkout_url`) OR sign the MPP challenge with `mppx`.
4. `GET /api/v1/jobs/{id}/upload-url` → presigned R2 PUT URL (402 + challenge if unpaid).
5. `PUT` the file bytes to the presigned URL.
6. `POST /api/v1/jobs/{id}/complete-upload` → verifies upload, starts processing.
7. Poll `GET /api/v1/jobs/{id}` until `status="completed"`.
8. `GET /api/v1/jobs/{id}/outputs/{role}/download`. Transcripts accept `?format=txt|vtt|json|words`.

### No-upload — `extract_clip`, `extract_vertical_clip`

Cuts from a parent job's already-uploaded source. No upload, no re-transcribe.

1. `POST /api/v1/jobs` with `{job_type, source_job_id, segments | start/end}`.
2. `POST /api/v1/jobs/{id}/process` with `Authorization: Payment <MPP credential>` — verifies payment AND starts processing.
3. Poll status, download as above.

## Source reuse

After `find_clips` completes, the source video stays in storage for **72 hours**. `transcribe` and `summarize` parents stay for **24 hours**. Pass the parent `job_id` as `source_job_id` to `extract_clip` / `extract_vertical_clip` and they cut from the cached source — no re-upload, no re-transcribe, just $0.50 per cut.

## Supported formats

**Input audio:** MP3, WAV, M4A, OGG, FLAC, WebM, AAC audio
**Input video:** MP4, MOV, WebM, MKV, AVI video
**Transcript output:** `srt`, `txt`, `vtt`, `json` (v1, segments only), `words` (v2, segments + per-word timestamps — schema at https://api.weftly.ai/.well-known/weftly-transcript-v2.schema.json)
**Clip discovery output:** JSON matching https://api.weftly.ai/.well-known/weftly-clips-v1.schema.json

## Schemas served at /.well-known

- `weftly-transcript-v2.schema.json` — word-level transcript format
- `weftly-clips-v1.schema.json` — `find_clips` ranked candidates
- `weftly-subjects-v1.schema.json` — subject reframing data (vertical-clip pipeline)

## MCP path (recommended for agents)

Connect to `https://api.weftly.ai/mcp` (Streamable HTTP, protocol 2025-03-26). Tools: `transcribe`, `summarize`, `find_clips`, `extract_clip`, `extract_vertical_clip`, `complete_upload`, `get_job_status`, `mpp_smoke_test`.

Each paid tool returns `payment_required` with an MPP challenge (and a Stripe Checkout URL fallback for browser MCP hosts). Sign the challenge with `mppx`, retry with the credential, then upload + poll.

## Provider

Woven Record Media — support@weftly.ai — https://weftly.ai