---
title: "AI Content Drop API — Developer Documentation"
description: "AI Content Drop developer documentation: REST API with Bearer API keys, video and image generation endpoints, MCP server, A2A agent, OpenAPI spec, and rate limits."
canonical: "https://aicontentdrop.com/developers"
source: "https://aicontentdrop.com/developers"
---
## Authentication

Create an API key in your dashboard at [Settings → Integrations](https://aicontentdrop.com/settings/integrations) (any account works — the free tier includes 10 credits). Keys look like `acd_live_…` and are shown once at creation. Send them as `Authorization: Bearer` on every request. Each key can carry an optional daily credit ceiling, so an agent can never overspend the budget you set.

You can start without one: `GET /v1`, `GET /v1/models`, `GET /v1/models/{id}/cost`, and `POST /ask` need no key at all. A key is only required to spend credits or read an account.

## Billing model

Generation costs flat credits per model — the catalogue lists the exact price of every model up front, and `/v1/models/{id}/cost` quotes a batch before you commit. Credits are only charged when a generation succeeds: safety blocks, provider failures, and timeouts cost nothing.

## CLI and SDKs

`aicontentdrop` is the official package in two ecosystems: [npm](https://www.npmjs.com/package/aicontentdrop) (TypeScript SDK + the `acd` CLI) and [PyPI](https://pypi.org/project/aicontentdrop/) (Python 3.9+). Neither has runtime dependencies, so the read commands work through `npx` with nothing installed and no API key.

```
# No install, no key — read commands work immediately
npx aicontentdrop models --type video --max-credits 15
npx aicontentdrop ask "which models generate audio?"

# Python: pip install aicontentdrop  (zero dependencies)
python -c "from aicontentdrop import AiContentDrop; print(AiContentDrop().models(type='video', max_credits=15))"

# Install the CLI, then generate
npm install -g aicontentdrop
export ACD_API_KEY=acd_live_YOUR_KEY

acd generate "a golden retriever surfing at sunset" \
  --model kling_3_0 --wait

# Rehearse without spending credits
acd generate "…" --model kling_3_0 --sandbox
```

Every command prints JSON by default so scripts and agents can parse it; `--pretty` is for humans. The SDK sends an idempotency key on every generation, so a retry after a dropped connection cannot charge twice.

## Quick start

```
# 1. Who am I? (verifies the key)
curl https://aicontentdrop.com/v1/me \
  -H "Authorization: Bearer acd_live_YOUR_KEY"

# 2. Pick a model
curl "https://aicontentdrop.com/v1/models?type=video&max_credits=30" \
  -H "Authorization: Bearer acd_live_YOUR_KEY"

# 3. Generate
curl -X POST https://aicontentdrop.com/v1/generate/video \
  -H "Authorization: Bearer acd_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "a golden retriever surfing at sunset", "aiModel": "kling_3_0" }'
# → { "video": { "id": "…", "status": "generating", … } }

# 4. Poll until status is "completed"
curl https://aicontentdrop.com/v1/videos/VIDEO_ID \
  -H "Authorization: Bearer acd_live_YOUR_KEY"
```

## Endpoints

| Endpoint | Description |
| --- | --- |
| `GET /v1` | Machine-readable index of the whole API. No API key required. |
| `GET /v1/me` | Account, plan, and credit balance — the first call every integration makes. |
| `GET /v1/models` | Model catalogue with flat credit costs. Filter with ?type=video|image and ?max_credits=N. No API key required. |
| `GET /v1/models/{id}/cost` | Credit cost estimate for a model before committing. ?quantity=N quotes several. No API key required. |
| `POST /v1/generate/video` | Start a video generation. Returns 202 with a Location header to poll. Send Idempotency-Key so a retry cannot double-charge; X-Sandbox: true to rehearse free. |
| `POST /v1/generate/image` | Start an image generation. Same 202 submit-and-poll contract as video. |
| `GET /v1/videos/{id}` | Poll one generation — status moves from generating to completed with a video_url. |
| `GET /v1/videos` | List recent generations, newest first. Page by following next_cursor until it is null. |
| `POST /v1/models/cost` | Quote up to 50 model/quantity pairs in one call. No API key required. |
| `POST /ask` | Natural-language query over the model catalogue and our guides (NLWeb). Returns Schema.org-shaped JSON. No API key required. |

The full request and response schemas — typed parameters, operation IDs, and error shapes compatible with LLM function calling — are in the OpenAPI 3.1 spec at [/openapi.json](https://aicontentdrop.com/openapi.json).

## Errors

Every failure returns structured JSON — never an HTML page — with a stable machine-readable `code` and a human-readable `message`:

```
{
  "error": {
    "code": "not_found",
    "message": "No video with that id"
  }
}
```

Common codes: `invalid_request` (400), `unauthorized` (401), `not_found` (404), `limit_reached` (409), `internal_error` (500).

## Rate limits

The public API allows **120 requests per minute**. Every response carries the standard `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers so clients can self-throttle in real time. A 429 additionally sends `Retry-After` in seconds — wait that long, then resume. Generation endpoints have their own hourly budgets on top; the error message names the window.

## Versioning and deprecation policy

The API version lives in the URL path. Everything documented here is `v1`, and `/v1` will keep answering for as long as it exists. Our commitments, so you can integrate without watching this page:

- Additive changes ship without notice.
  
  New endpoints, new optional request fields, and new response fields can appear at any time. Parse defensively: ignore response fields you do not recognise rather than failing on them.
- Breaking changes get a new path.
  
  Removing a field, renaming one, or changing a type means
  
  /v2
  
  , never a silent change to
  
  /v1
  
  .
- Deprecation is announced in headers, not blog posts.
  
  A deprecated endpoint returns
  
  Deprecation
  
  (RFC 9745) and
  
  Sunset
  
  (RFC 8594) response headers, plus a
  
  Link; rel="successor-version"
  
  pointing at the replacement. Log those headers and you get the warning automatically.
- Minimum 180 days.
  
  From the first
  
  Sunset
  
  header to removal is at least 180 days. Model IDs follow the same rule: a retired model keeps returning a clear
  
  unknown_model
  
  error rather than silently substituting a different one.

No endpoint is deprecated today, so no `Sunset` header is currently sent by any response. The machine-readable form of this policy is in the [OpenAPI spec](https://aicontentdrop.com/openapi.json) and under `versioning` in [GET /v1](https://aicontentdrop.com/v1).

## MCP server & A2A agent

AI agents can skip raw HTTP entirely. Our MCP server at `POST /mcp` (streamable HTTP) exposes the model catalogue and articles anonymously, and unlocks generation tools when the client presents an API key — setup guide at [/mcp/claude-code](https://aicontentdrop.com/mcp/claude-code), manifest at [/.well-known/mcp.json](https://aicontentdrop.com/.well-known/mcp.json). An A2A agent lives at `POST /a2a` with its card at [/.well-known/agent-card.json](https://aicontentdrop.com/.well-known/agent-card.json).

## Machine-readable resources

- /openapi.json
  
  — OpenAPI 3.1 spec for everything on this page
- /llms.txt
  
  — curated site overview for AI agents
- /auth.md
  
  — what agents may do on a user's behalf
- /.well-known/api-catalog
  
  — RFC 9727 API catalogue
- /sitemap.xml
  
  — every indexable URL
- /.well-known/ai-catalog.json
  
  — Agentic Resource Discovery catalogue
- /?mode=agent
  
  — machine-readable homepage
- /developers/llms.txt
  
  — scoped context for this page