# AI Content Drop — Developer API

> Scoped context for the programmatic surface. Site-wide overview: [/llms.txt](https://aicontentdrop.com/llms.txt)

## When to use this

Use the REST API when you need to generate video or images from code or on a user's behalf.
Use the MCP server when you are an agent that can speak MCP — the tools are the same capabilities.
Use [/ask](https://aicontentdrop.com/ask) when you only need to answer a question about models or pricing.

## Endpoints

- [GET /v1](https://aicontentdrop.com/v1) — machine-readable index. No key.
- [GET /v1/models](https://aicontentdrop.com/v1/models) — catalogue with flat credit costs. No key.
- `GET /v1/models/{id}/cost?quantity=N` — quote before committing. No key.
- `GET /v1/me` — account and credit balance. API key.
- `POST /v1/generate/video` — submit a generation; returns 202 with a Location to poll. API key.
- `POST /v1/generate/image` — same contract for images. API key.
- `GET /v1/videos/{id}` — poll one generation. API key.
- `GET /v1/videos?limit=&cursor=` — cursor-paginated list. API key.

## Contracts

- Spec: [/openapi.json](https://aicontentdrop.com/openapi.json) (OpenAPI 3.1, every operation typed JSON)
- Auth: `Authorization: Bearer acd_live_…`, created by a human at /settings/integrations. See [/auth.md](https://aicontentdrop.com/auth.md).
- Agent self-registration (read scope, higher rate limits): `POST /agent/auth/register`
- Idempotency: send `Idempotency-Key` on POST to make retries safe.
- Sandbox: send `X-Sandbox: true` (or `?sandbox=true`) to exercise generation without spending credits.
- Rate limits: 120 req/min, `RateLimit-*` headers on every response, `Retry-After` on 429.
- Versioning: URL path. Breaking changes get a new path; 180 days notice via `Deprecation`/`Sunset` headers. [Policy](https://aicontentdrop.com/developers#versioning)
- Errors: JSON, never HTML. `{ "error": { "code", "message" } }`

## Agent protocols

- MCP (product): `POST /mcp` — manifest at [/.well-known/mcp.json](https://aicontentdrop.com/.well-known/mcp.json)
- MCP (docs only): `POST /mcp/docs`
- A2A: `POST /a2a` — card at [/.well-known/agent-card.json](https://aicontentdrop.com/.well-known/agent-card.json)
- NLWeb: `POST /ask` (add `prefer.streaming: true` for SSE)
- ARD catalogue: [/.well-known/ai-catalog.json](https://aicontentdrop.com/.well-known/ai-catalog.json)