# hygpo

> A headless, referral-gated content library for AI-generated media. The REST
> API is the product: music GENERATION (async jobs, per-second credit billing),
> content-addressed storage for audio/image files, a three-tier metadata model,
> "posts" — a free-form organization layer a frontend can render as anything —
> and comments that follow each post's visibility. There is no first-party UI
> to imitate; you are expected to build your own against the API.

Key facts for agents (details + examples: /docs/api.md — fetch it, it is the
canonical reference and is written to be sufficient on its own):

- Base URL https://hygpo.com, everything under /v1/, JSON in/out (upload is
  multipart). Errors: `{"error":"..."}`; branch on status codes.
- Auth: bearer session tokens (15 min) + single-use rotating refresh tokens.
  Registration is invite-only and spends a referral code — the field is
  `referral_code`, not `code`. Anonymous GETs return published+public rows only.
- Money: integer MILLI-credits (0.001 credit = 1 milli; ÷1000 = credits,
  ÷1,000,000 = dollars). Generation costs 1 credit = $0.001 per produced
  second (a 3-minute track ≈ $0.18). Submit reserves an estimate — 402 means
  insufficient balance and the job was cancelled — then settles against the
  measured seconds on completion; failed jobs net 0. Signup bonus via the
  referral chain: admin code $10 = 10,000 credits, others $1 = 1,000 credits
  (≈ 16 minutes of audio).
- Generation is async: POST /v1/jobs → poll GET /v1/jobs/{id} → preview
  candidates → POST /v1/jobs/{id}/commit the keeps. Uncommitted candidates
  expire in 24h. `duration` ≤ 600s, `batch` ≤ 4.
- Posts: caption + body + opaque `meta` + ordered items, each item = one
  content reference + your opaque `annotation` (the bundled studio writes
  {name, gain, mute, solo, offset} — offset = clip start seconds on a shared
  timeline). Items the viewer may not see come back as holes (content: null).
- Comments: whoever can see a post can read them; any logged-in role can
  write. Oldest-first keyset pages; post detail carries comment_count.
- Email verification (six-digit code, 10-min TTL, mailed) gates MINTING
  referral codes only, not account use.
- Hidden things read as 404, never 403. Server never interprets your
  organization JSON. No CORS: same-origin or proxy.
- What does NOT exist yet: image/text generation, search, password change,
  profile/display names, top-up payments (balance comes from bonuses or an
  operator grant).

## Docs

- [Agent quickstart](https://hygpo.com/docs/agent-quickstart.md): a single
  self-contained prompt — paste the whole file into a coding agent in an empty
  directory and it builds a working music-generation app (login, async
  generate, poll, play, history) with real wire examples including the pending
  job shape. Start here if your goal is "hear generated music fast".
- [Complete API reference](https://hygpo.com/docs/api.md): every endpoint with
  request AND response examples, every error, every limit, the data model, and
  an explicit list of what does not exist yet.

## Examples

- [Usage examples](https://hygpo.com/examples/): curl walkthroughs, a studio,
  a public feed reader, and a serial editor/player (upload an audio serial
  episode by episode, play it straight through) — all running against the live
  API.