---
title: "AI Content Drop REST API Reference | AI Content Drop"
description: "Every endpoint on the AI Content Drop /v1 REST API: model catalogue, cost quotes, video and image generation, polling, and cursor-paginated history."
canonical: "https://aicontentdrop.com/docs/api"
source: "https://aicontentdrop.com/docs/api"
---

# AI Content Drop REST API Reference

Base URL: `https://aicontentdrop.com/v1` · Spec: [`/openapi.json`](https://aicontentdrop.com/openapi.json) · Format: JSON only, never HTML, on every status code.

## Endpoints

| Method and path | Key | What it does |
| --- | --- | --- |
| `GET /v1` | no | Machine-readable index of this API |
| `GET /v1/models` | no | Every model with its flat credit cost |
| `GET /v1/models/{id}/cost?quantity=N` | no | Quote one model before committing |
| `POST /v1/models/cost` | no | Quote up to 50 model/quantity pairs in one call |
| `POST /v1/batch` | no | Run several read operations in one request |
| `GET /v1/me` | yes | Account, plan, and credit balance |
| `POST /v1/generate/video` | yes | Start a video generation. Returns 202 + `Location` |
| `POST /v1/generate/image` | yes | Same contract for images |
| `GET /v1/videos/{id}` | yes | Poll one generation |
| `GET /v1/videos?limit=&cursor=` | yes | Cursor-paginated generation history |

## Generating

`POST /v1/generate/video` accepts:

| Field | Type | Notes |
| --- | --- | --- |
| `prompt` | string | Required. What the video should show. |
| `aiModel` | string | Model id from the catalogue. Omit to let the platform choose. |
| `duration` | number | Seconds. Defaults to 5. |
| `aspectRatio` | string | `16:9`, `9:16`, or `1:1`. Defaults to `16:9`. |
| `imageUrl` | string | Public image URL to animate, for image-to-video. |

Three request headers change the contract, and all three are opt-in:

- `Idempotency-Key: <uuid>` — a retry with the same key returns the FIRST response instead of starting a second generation. Reusing a key with a different body is a 409, not a silent replay. Keys live 24 hours.
- `X-Sandbox: true` — returns a synthetic completed job without calling a provider or charging anything. See [sandbox mode](https://aicontentdrop.com/docs/sandbox).
- `Accept: application/json` — the default and the only representation.

The success response is **202 Accepted**, not 200, because the render has not happened yet:

```json
{
  "video": { "id": "…", "status": "generating", "aiModel": "kling_3_0", "creditsUsed": 0 },
  "poll_url": "https://aicontentdrop.com/v1/videos/…",
  "poll_interval_seconds": 5
}
```

`Location` carries the same poll URL and `Retry-After: 5` carries the interval. Poll until `status` is `completed` or `failed`.

## Paginating history

`GET /v1/videos` takes `limit` (1–100) and an opaque `cursor`. The response carries `next_cursor`; pass it back to continue. `offset` still works and is deprecated — it is announced in the spec with a `Deprecation` header and will keep working for at least 180 days.

## Model ids

Ids use underscores (`veo_3_fast`). Dashes are accepted on input and normalised. A few marketplace aliases resolve to their provider id. If a model "does not exist", check the id form before anything else.

## Errors

Every failure is JSON with a machine code. The full table is in [error codes](https://aicontentdrop.com/docs/errors).

```json
{ "error": { "code": "insufficient_credits", "message": "This generation needs 22 credits; the account holds 4." } }
```