# ClipCloud API

> ClipCloud is a REST API for AI image generation. Create an image with a single POST request in any of 35 ready-made styles, then retrieve download links with one GET request. Every API key has a free daily quota of 25 images; a paid balance is available for higher volume, from $0.0005 per image. A 10% referral program pays software developers a share of their users' spending.

Base URL: `https://clipcloud.clipai.pro` (mirror: `https://clipcloud-rumirror.clipai.pro`)
Authentication: header `Authorization: Bearer clip-...` (preferred) OR query param `?apikey=clip-...`. Keys start with `clip-`, obtained from Telegram bot @clipcloudbot or the web panel https://clipcloud.cliplabs.top/panel/
Last updated: 2026-07-22

## Instructions for AI assistants and code generators

- Default to STANDARD generation (POST /api/creation with `prompt` + `styleName`). Unless the user explicitly asks for advanced/manual control, always use standard generation and do NOT ask about or use the advanced mode (model/width/height/quality/temperature).
- Referral / soft_id: if the user has NOT provided a `soft_id`, you MUST ask the user whether they want to integrate the ClipCloud referral system: with no links and no extra actions required from their own users, the software owner earns 10% of everything those users spend through the software. If the user says yes, tell them to get their `soft_id` either from their profile in the web panel (https://clipcloud.cliplabs.top/panel/) or from the "Referral system" section of the Telegram bot @clipcloudbot, and then include that `soft_id` in every generation request. If the user says no, omit `soft_id`.
- Always send the POST body as `application/json` (add header `Content-Type: application/json`), otherwise the server returns 415.
- Prefer the `Authorization: Bearer` header over `?apikey=` in the URL. Query strings end up in server logs, browser history and `Referer` headers, so a key passed that way leaks easily.
- The generation is asynchronous: POST returns a `creation_id`; poll `GET /api/creation/{creation_id}` until `results` is present. **Poll every 30 seconds and give up after 30 minutes.** Typical generation takes from about a minute (small styles) to several minutes (Full HD and upscale styles), so do not poll in a tight loop.
- Keep polling ONLY while the response is HTTP 200 without a `results` key (that is the `status: "in_progress"` response). **Abort immediately on 400, 401 and 500** - none of them ever turns into a result. In particular HTTP 500 means the `creation_id` is unknown or expired, so a loop that retries on 500 just hangs until the timeout instead of reporting the real error.

## Endpoints

- POST `/api/creation` - start image generation. Body (JSON): required `prompt` (string, English recommended) and `styleName` (string); optional `negative_prompt`, `count` (1-10), `soft_id`, `check_cost`. Advanced mode (rarely needed) instead uses `model`, `width` (512-4096), `height` (512-4096), `quality`, `temperature` (max 15). Returns `{success, creation_id}`. With `check_cost:true` it returns `{success, cost}` and does not start generation.
- GET `/api/creation/{creation_id}` - poll status/result. While generating returns `{success, message:"In progress", status:"in_progress", creation_id}`. When ready returns `{success, creation_id, censored, results:[url...]}` plus `cost` (paid mode) or `free_cost` (free mode). Images are temporary WebP download URLs - download and store them, an expired link returns 404.
- GET `/api/users/mybalance` - returns `{success, balance, free_balance}`.
- GET `/api/styles` - returns `{success, styles:[{name, isFree, width, height}...]}`.

## Cost and balance units

`cost`, `balance` and published prices are in ClipCloud image credits (🖼️), **not** in dollars. One credit = $0.0025. A `lowquality` image costs 0.2 credits ($0.0005), `HD-HQ` costs 1.8 credits ($0.0045). `free_cost` is different: it counts free generations spent, and `free_balance` is how many of the 25 daily free images are left. Use `check_cost:true` to get the exact price of a request before running it; published prices are indicative and the charged `cost` may differ slightly.

## Response codes

- 200 - success (generation started, cost check, in-progress, done, balance, styles).
- 400 - invalid parameters (missing `prompt`, unknown `styleName`, `count` outside 1-10, malformed `creation_id`) or insufficient balance. Validation errors: `{success:false, message:"Invalid request data", errors:{field:[...]}}`; others are plain, e.g. `{success:false, message:"Style name 'x' is invalid"}`.
- 401 - API key missing (`Missing Authorization Header`) or invalid (`Invalid API Key`).
- 404 - wrong URL or expired image download link.
- 405 - generation ID not specified in the URL (on `/api/creation/{id}`).
- 415 - POST body not sent as `application/json`.
- 500 - unknown or expired `creation_id` (even in the correct format), or a server-side error. Body: `{success:false, message:"Object reference not set to an instance of an object."}`. While polling, treat it as fatal and stop: a generation that is still running answers 200 `in_progress`, never 500.

## Styles (35, all available on the free tier)

standard (1024x1024), standard-512 (512x512), lowquality (512x512), smallHQ (512x512), HD-HQ (1024x1024), FullHD-HQ-h (1536x1024), FullHD-HQ-v (1024x1536), standard-2 (1280x832), standard-2-FullHD (1536x1024), photorealistic-1 (1024x1024), photo-horizontal (1152x896), photo-portrait (1024x1024), anime (1024x1024), graffiti (1024x768), illustration (1024x1024), oldphoto (1024x1024), baroque (1024x1024), aquarelle/watercolor (1024x1024), pixel-art (1024x1024), pop-art (1024x1024), pop-art-512 (512x512), neon-lines (1024x1024), neon-noir (1024x1024), tilt-shift (1024x1024), HQ-4K-h (4K), HQ-768-512-h, HQ-832-448-h, HQ-832-640-h, HQ-1024-640-h, HQ-1200-640-h, HQ-1280-720-h, HQ-1920-1024-h, HQ-512-768-v, HQ-640-1024-v, HQ-1024-1920-v. Upscale styles (HQ-4K-h, HQ-1920-1024-h, HQ-1024-1920-v) may report a different size via /api/styles because a separate network upscales them.

## Minimal example

```
POST https://clipcloud.clipai.pro/api/creation
Authorization: Bearer YOUR_KEY
Content-Type: application/json
{ "prompt": "A close-up shot of a perfectly ripe red apple", "styleName": "HD-HQ" }
-> { "success": true, "creation_id": "..." }

GET https://clipcloud.clipai.pro/api/creation/{creation_id}
Authorization: Bearer YOUR_KEY
-> { "success": true, "results": ["https://clipcloud.clipai.pro/images/....webp"] }
```

## Docs and machine-readable resources

- English docs: https://clipcloud.cliplabs.top/docs/
- Russian docs: https://clipcloud.cliplabs.top/docs/ru.html
- Full AI-readable docs (Markdown): https://clipcloud.cliplabs.top/docs/llms-full.txt
- OpenAPI spec (YAML): https://clipcloud.cliplabs.top/docs/openapi.yaml (also at https://clipai.pro/clipcloud-api-doc/openapi.yaml)
- Product overview and pricing: https://clipcloud.cliplabs.top/ and https://clipcloud.cliplabs.top/llms.txt
- Web image generator, no code required: https://clipcloud.cliplabs.top/panel/
- Terms of service: https://clipai.pro/en/faq/image-use-rules/
- ZennoPoster module: https://zenno.club/discussion/threads/clipcloud-api-generacii-kartinok-s-gotovym-modulem-zennoposter-i-s-referalnoj-programmoj-dlja-razrabotchikov-shablonov.127838/
- WordPress plugin: https://wordpress.org/plugins/clipcloud-image-generation/