Clipamo API

Public clip search and delivery

Search the clip catalog with natural language, then fetch the returned clips directly from the reconstructed public GCS URL.

Open app

Base URL

https://clipamo.beny.io

`GET /api/search` and `POST /api/search` require an API key. Use either `x-api-key: YOUR_CLIPAMO_API_KEY` or `Authorization: Bearer YOUR_CLIPAMO_API_KEY`. Search responses include both the canonical `gs://...` path and a public `clipUrl` you can fetch directly.

Search with GET

Best for simple query strings and quick manual testing.

curl -G https://clipamo.beny.io/api/search \
  -H "x-api-key: YOUR_CLIPAMO_API_KEY" \
  --data-urlencode "query=best friends cards with save and share actions"

Search with POST

Best for server-to-server integrations sending JSON bodies.

curl https://clipamo.beny.io/api/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_CLIPAMO_API_KEY" \
  -d '{"query":"friends list with intros and mutuals"}'

Search response

{
  "query": "best friends cards with save and share actions",
  "clips": [
    {
      "path": "gs://amo-bo-public/content-factory/clips-fridge/all-features/top-best-friends/tap-best-friends-and-scroll-through-a-few.mp4",
      "explanations": "This clip directly shows best-friends cards with visible save and share buttons.",
      "score": 98,
      "clipUrl": "https://storage.googleapis.com/amo-bo-public/content-factory/clips-fridge/all-features/top-best-friends/tap-best-friends-and-scroll-through-a-few.mp4",
      "viewerUrl": "https://clipamo.beny.io/clip?path=gs%3A%2F%2Famo-bo-public%2Fcontent-factory%2Fclips-fridge%2Fall-features%2Ftop-best-friends%2Ftap-best-friends-and-scroll-through-a-few.mp4"
    }
  ],
  "meta": {
    "model": "gpt-5.4",
    "mode": "llm-rerank",
    "catalogSize": 680,
    "shortlisted": 36,
    "returned": 5,
    "latencyMs": 742
  }
}

Clip object fields

path

Stable clip identifier. Send this value back unchanged when you want the file.

explanations

Why the clip matched the query.

score

Relevance score from 0 to 100.

clipUrl

Direct public GCS URL for the clip.

viewerUrl

Hosted browser viewer for the clip.

Meta fields

model

Model used for reranking.

mode

Either llm-rerank or prefilter-fallback.

catalogSize

Total catalog entries considered by the service.

shortlisted

Candidates sent into final ranking.

returned

Always 5 when the catalog has enough matches.

latencyMs

Server-side search latency in milliseconds.

warnings

Optional fallback notes, for example when OpenAI reranking is unavailable.

Fetch the clip file

Use `clipUrl` directly. It is derived from the returned `gs://...` path and points at the public GCS object.

curl -L \
  "https://storage.googleapis.com/amo-bo-public/content-factory/clips-fridge/all-features/top-best-friends/tap-best-friends-and-scroll-through-a-few.mp4" \
  --output clip.mp4

Common errors

Search returns `401` for missing auth, `400` for missing or short queries, and `500` or `502` only when the service cannot assemble results.

{
  "error": "unauthorized",
  "message": "Provide x-api-key or Authorization: Bearer <token> with the value from CLIPAMO_API_KEY."
}