# CheapAIAPI API documentation

CheapAIAPI provides image, text, and video generation APIs for production workloads.
The OpenAPI specification is the authoritative public HTTP contract.

## Developer resources

- [Interactive CheapAIAPI API reference](https://cheapaiapi.org/docs)
- [CheapAIAPI OpenAPI specification](https://cheapaiapi.org/openapi.json)
- [Models and account-specific pricing](https://cheapaiapi.org/v1/models)
- [Public models and pricing pages](https://cheapaiapi.org/models/)
- [Public starting prices in Markdown](https://cheapaiapi.org/pricing.md)
- [Public starting prices as JSON](https://cheapaiapi.org/pricing.json)
- [Agent integration guide](https://cheapaiapi.org/llms.txt)
- [CheapAIAPI for coding agents](https://cheapaiapi.org/for-agents)
- [Image webhook guide](https://cheapaiapi.org/docs/webhooks.md)
- [Request access or integration help](https://cheapaiapi.org/contact)

## Pricing and access

CheapAIAPI is a prepaid, usage-based API with no monthly or annual subscription.
The public catalog contains real starting prices for new customers. Customers
with existing production volume may qualify for lower account-specific rates by
sending the exact model, current monthly usage, and average and peak RPS through
[CheapAIAPI contact](https://cheapaiapi.org/contact).

## Authentication

Send the issued API key as `Authorization: Bearer sk_cheap_...`. API keys are
issued after account approval. Unauthenticated `/v1/*` requests return HTTP 402
with access links to starting prices and contact. Invalid or revoked keys return
HTTP 401. The 402 body is not a cryptocurrency payment quote.

## Video generation

Call `GET /v1/models` for the video models and exact rates enabled for your
account. Create a Seedance 2.5 image-to-video Job with the official request
shape:

```json
{
  "model": "seedance-2.5",
  "content": [
    {"type": "text", "text": "Animate this image."},
    {
      "type": "image_url",
      "image_url": {"url": "https://example.com/direct-image.jpg"},
      "role": "first_frame"
    }
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "adaptive"
}
```

Send this body to `POST /v1/videos` with an `Idempotency-Key`. Seedance 2.0
accepts durations from 4 to 15 seconds and defaults to 5. Seedance 2.5 requires
a duration from 4 to 30 seconds. `input_image` is unsupported; use
`content[].image_url.url` as shown above.

Input media must be a direct public HTTPS file that returns the image without
authentication, cookies, a login, or a sharing page, and it must remain valid
until generation finishes. CheapAIAPI image-result URLs require the owning
account's bearer key, so they cannot be used directly as video inputs. Download
the image through authorized access, copy it to public HTTPS storage you
control, and submit that copy's URL.

Poll `GET /v1/videos/{id}` until `status` is `completed` or `failed`. Download
a completed video with the same bearer key from `GET /v1/videos/{id}/content`.
When an input image cannot be downloaded, the failed video returns
`error.code: "InvalidPrompt"` and this message: "The input image could not be
downloaded. Use a public HTTPS URL that returns the image directly, without
authentication, and remains valid until generation finishes."
Other `InvalidPrompt` failures use: "The video request could not be generated.
Check the prompt and input images. For image input, use a public HTTPS URL that
returns the image directly, without authentication, and remains valid until
generation finishes."

## Image Job completion

Recommended production flow for image Jobs:

1. Call `POST /v1/images/generations?async=true` with `webhook_url`.
2. Store the returned Job `id`.
3. Handle the signed callback as the primary completion path.
4. Recover with `GET /v1/jobs/{id}` if no callback arrives.

Read `webhook_secret` from `GET /v1/balance`. The full guide is
[https://cheapaiapi.org/docs/webhooks.md](https://cheapaiapi.org/docs/webhooks.md).
Chat Completions and video do not accept `webhook_url`.

## Low-latency integration

These are the defaults for a fast integration. Each one removes avoidable delay
that is not image generation time. The full checklist with a request example is
at [https://cheapaiapi.org/docs/webhooks.md#low-latency-integration](https://cheapaiapi.org/docs/webhooks.md#low-latency-integration).

- Create image Jobs with `?async=true` plus `webhook_url` and treat the signed
  callback as the completion path. Poll `GET /v1/jobs/{id}` only as recovery,
  every 5 seconds and never faster than every 2 seconds.
- Pass reference images as inline `data:image/<mime>;base64,...` bytes instead
  of `https://` URLs. A URL input may have to be fetched before generation can
  start; inline bytes never need that round trip.
- Send each reference image at the resolution you actually need and do not
  compress the request body. One reference image may be at most 25 MiB and the
  whole `image` array at most 50 MiB.
- Send a stable `Idempotency-Key` per client-side Job and reuse it when
  retrying, and reuse one HTTP/1.1 keep-alive or HTTP/2 connection pool instead
  of opening a new TLS connection per request.
- Download `data[].url` as soon as the Job is `done`. Result links are not
  durable storage: treat the `X-Result-Retention-Days` response header
  (currently 7) as an upper bound and expect at most 25 MiB per image. Contact
  us before sustaining a submission rate above the published standard image
  baseline.

## Recommended generation flow

1. Call `GET /v1/models` to discover the SKUs and prices enabled for the account.
2. Submit a generation request with a stable `Idempotency-Key`.
3. Store the returned job `id`.
4. For image Jobs, pass `webhook_url` and treat `GET /v1/jobs/{id}` as
   recovery. For other products, poll the documented job endpoint.

## Image input capabilities

- The optional `image` array accepts public `https://` URLs and `data:image/<mime>;base64,...` data URIs.
- Every `nano-banana-2-*` SKU accepts at most 14 images.
- Every `nano-banana-pro-*` SKU accepts at most 14 images.
- The base `nano-banana` SKU accepts at most 4 images.
- Every `gpt-image-*` SKU accepts at most 10 images. The default hard ceiling for other
  image SKUs is 10.
- OpenAPI exposes the global ceiling as `maxItems: 14` plus an exact model-limit
  map; when several selectors match a model, the longest matching selector wins. Authenticated
  `GET /v1/models` returns the effective hard limit for each enabled image SKU at
  `capabilities.image_input.max_items`.