# Media API on API Mercado

> Turn YouTube videos and audio files into word-level transcripts, speaker diarization, voice fingerprints, and rich metadata with fast, reliable APIs. Published by Capital Enesti and sold through API Mercado, an API marketplace: one gateway, one Key, pay per request from a prepaid balance.

This guide is for coding agents and developers. It explains how to get access, how to call this API through the gateway, and how to generate a typed client. Everything an agent needs is here or linked as markdown.

## Identifiers

- Human page: https://apimercado.com/discover/capitalenesti/media-api
- Provider: Capital Enesti, gateway segment `@capitalenesti` (the public id `e72bpbz582mh` is also accepted, for URLs copied before slugs existed)
- API slug: `media-api`
- Gateway base URL: `https://eu-north-1.apimercado.com/v1/@capitalenesti/media-api/`
- Same API under the legacy id URL: `https://eu-north-1.apimercado.com/v1/e72bpbz582mh/media-api/`
- OpenAPI document (no Key needed): https://eu-north-1.apimercado.com/v1/@capitalenesti/media-api/openapi.json
- Current version: 1.6.0

## 1. Get a Key (one-time, needs a human with an account)

1. Sign in at https://apimercado.com and pick or create an organization.
2. Open https://apimercado.com/discover/capitalenesti/media-api and press **Enable** (an org admin; it is instant, no approval).
3. Create a Key at https://apimercado.com/dashboard/keys. Keys start with `mk_live_`, are shown once, and spend the organization's balance, so keep them server-side, in an environment variable such as `APIMERCADO_API_KEY`.
4. Top up the balance at https://apimercado.com/dashboard/billing when the Free buffer is not enough.

## 2. Call it

Every request carries the Key in the `X-API-Key` header and goes to the gateway base URL plus the endpoint path from the OpenAPI document:

```sh
curl -i "https://eu-north-1.apimercado.com/v1/@capitalenesti/media-api/health" \
  -H "X-API-Key: $APIMERCADO_API_KEY"
```

- The gateway strips the Key, authenticates to the provider itself and forwards the request. Response headers `X-Mercado-Cost-Micros`, `X-Mercado-Fee-Micros` and `X-Mercado-Balance-Micros` report what the call cost (integer micro-dollars, 1,000,000 = $1.00).
- Pricing: $0.00 up to $2.00 per request, plus a $0.00005 proxy fee per request. The provider may charge up to $2.00 on heavier requests.
- Errors from the gateway itself are JSON `{ "error": { "code", "message" } }` with codes such as `key_not_authorized`, `api_not_enabled`, `balance_exhausted`, `key_spend_cap_reached`, `org_suspended` and `rate_limited`. Upstream errors pass through unchanged.
- Balance check without spending: `GET https://eu-north-1.apimercado.com/v1/account/balance` with the same header.

## 3. TypeScript client (recommended)

`@apimercado/client` wraps openapi-fetch with the gateway URL, the Key header and the gateway error shape. Generate the types once from the OpenAPI document and commit the file:

```sh
npm install @apimercado/client
npx @apimercado/client generate @capitalenesti/media-api -o media-api.d.ts
```

```ts
import { createApimercadoClient, readCost } from "@apimercado/client";
import type { paths } from "./media-api";

const media_api = createApimercadoClient<paths>({
  provider: "@capitalenesti",
  api: "media-api",
  apiKey: "mk_live_...", // read it from your environment, keep it server-side
});

const { data, error, response } = await media_api.GET("/health");
if (error) throw new Error(error.error.code);
console.log(data, readCost(response).costMicros);
```

In CI, `npx @apimercado/client check media-api.d.ts` exits 1 when the provider changed the spec; regenerate and let the compiler show what moved.

## 4. Any other language

Point an OpenAPI generator (openapi-generator, openapi-python-client, oapi-codegen, ...) at https://eu-north-1.apimercado.com/v1/@capitalenesti/media-api/openapi.json. Set the server URL to `https://eu-north-1.apimercado.com/v1/@capitalenesti/media-api/` and send `X-API-Key` on every request. The document already lists the gateway as its server.

## 5. Endpoints

- `GET /health`: Health check
- `POST /videos`: Register a File as a Video
- `GET /channel`: Look up a YouTube channel
- `GET /heatmap`: Fetch a video's Most replayed graph
- `GET /metadata`: Fetch video metadata and YouTube chapters
- `GET /playlist`: Browse playlist items
- `POST /embeddings`: Submit or poll an audio range embedding job
- `POST /transcripts`: Submit or poll a transcription job
- `POST /fingerprints`: Submit or poll a voice fingerprinting job
- `POST /metadata/batch`: Fetch metadata for multiple videos in batch
- `GET /playlist/since`: Fetch playlist items added after a timestamp
- `DELETE /videos/{videoId}`: Delete a File Video and everything made from it
- `POST /bust-cache/{videoId}`: Invalidate cached video assets
- `GET /transcripts/{videoId}`: Read one stored transcript at an exact version

Parameters, request bodies and response schemas are in the OpenAPI document above; the human reference is https://apimercado.com/discover/capitalenesti/media-api?tab=reference.

## More

- Billing, Keys, spend caps and every error code: https://apimercado.com/llms/billing-and-keys.md
- Selling your own API here: https://apimercado.com/llms/publish-an-api.md
- Every API and document on the marketplace: https://apimercado.com/llms.txt
- Provider terms: https://capitalenesti.com/terms
- Provider privacy policy: https://capitalenesti.com/privacy