ClipCloud API Documentation

A REST API for AI image generation: one POST request to create an image in any of 35 ready-made styles, one GET request to download the result. Free daily quota on every key, paid mode for volume, and a 10% referral program for software developers.

Main Information

The ClipCloud API is simple. There are just three steps:

Authentication

Every request must carry your API key, which always starts with clip-. You can get one from the Telegram bot @clipcloudbot or manage it in the web panel. Two equivalent ways to pass the key:

• Query parameter: ?apikey=clip-... (used in the examples below);
• HTTP header: Authorization: Bearer clip-...

Cost and balance: the 🖼️ credit

Prices and the cost field are counted in ClipCloud image credits, written 🖼️ — not in dollars. It is the same idea as tokens in a text-AI API: one small unit of account that keeps very different images comparable. The rate is fixed:

There are two separate counters, and they are easy to mix up — credits are not the same thing as free images:

Typical prices per image:

Published prices are indicative. For the exact price of a specific request, send it with check_cost: true: the server answers with the price and does not start a generation or spend anything.

Image Generation

If you plan to integrate ClipCloud into your software for multiple users, we recommend using only standard generation (by style).

Image generationStandard generation (by style)

Generate an image by choosing a style. This is the recommended way for everyone.Standard image generation by style, recommended for all service users.

As a result of this request you will receive the ID of the started generation. It will be one, even if you specify count > 1. This ID will be needed later to obtain the result of creating the image or images.

Only the prompt and styleName parameters in the request body, and apikey in the request URL, are mandatory.

POST request, data format: application/json (as, for example, in the GPT API).

Query Parameters

Body Parameters

Supported styles (styleName values)

Note: for upscale styles (e.g. HQ-4K-h, HQ-1920-1024-h, HQ-1024-1920-v) the width and height returned by GET /api/styles may differ from the final image size, because a separate neural network upscales their quality. Working with such styles is no different from using any other style.

Responses

{
  "success": true,
  "creation_id": "12345678-abcd-ef12-3456-7890abcdef12"
}

{
  "success": true,
  "cost": 0.7
}

{
  "success": false,
  "message": "Invalid request data",
  "errors": { "prompt": ["The prompt field is required."] }
}

{
  "success": false,
  "message": "Style name 'nosuchstyle' is invalid"
}

{ "success": false, "message": "Invalid API Key" }

Example

▶ Try in API Explorer

Advanced generation (with additional parameters)

Obtaining Results

GET request. In the request URL: your API key and the generation ID obtained earlier in the image-generation request response. The response contains the link(s) to the generated images (one link per image).

Path Parameters

Responses

{
  "success": true,
  "message": "In progress",
  "status": "in_progress",
  "creation_id": "12345678-abcd-ef12-3456-7890abcdef12"
}

{
  "success": true,
  "message": "Images processed succesfully",
  "creation_id": "12345678-abcd-ef12-3456-7890abcdef12",
  "cost": 2.2,
  "censored": 0,
  "results": [
    "https://clipcloud.clipai.pro/images/326432e4661c42d709432284c836d410b5.webp",
    "https://clipcloud.clipai.pro/images/c9436e4e57c1d9b2eb81b48d85a98a88c1.webp"
  ]
}

{
  "success": true,
  "message": "Images processed succesfully",
  "creation_id": "12345678-abcd-ef12-3456-7890abcdef12",
  "free_cost": 1,
  "censored": 0,
  "results": [
    "https://clipcloud.clipai.pro/images/9f40fb913134b6cc209459798ebb5623cd_free.webp"
  ]
}

{
  "success": false,
  "message": "Invalid request data",
  "errors": { "creation_id": ["The value 'notanid' is not valid."] }
}

{ "success": false, "message": "Invalid API Key" }

{ "success": false, "message": "Object reference not set to an instance of an object." }

Example

▶ Try in API Explorer

Other Requests

In this category you'll find miscellaneous requests that may be useful (but are not mandatory) in certain program workflows: checking the API-key balance and retrieving available styles.

Balance Inquiry

GET request. The API key is in the request URL. The response contains information about that API key's balance.

Responses

{
  "success": true,
  "balance": 431.9,
  "free_balance": 25
}

{ "success": false, "message": "Invalid API Key" }

Example

Available Styles

GET request. The API key is in the request URL. The response contains up-to-date information about existing styles.

More detailed information about the styles, with clear names and descriptions, can be found in the style table above.

Responses

{
  "success": true,
  "styles": [
    { "isFree": true, "name": "standard", "width": 1024, "height": 1024 },
    { "isFree": true, "name": "smallHQ", "width": 512, "height": 512 }
  ]
}

Example

API Usage Examples

For generating images from a predefined prompt

The API is extremely simple to integrate and use. To create an image and obtain the result you only need to perform:

• One POST request with two parameters;
• One GET request with one parameter.

Even if you use the minimum number of parameters, as shown here, image quality will be excellent in most cases.

Assume you need to generate one image for the prompt "A close-up shot of a perfectly ripe red apple". Because you want a high-quality, realistic picture, you choose the HD-HQ style (the full list of styles can be found in the styleName table). Send a POST request to:

https://clipcloud.clipai.pro/api/creation?apikey=YOUR_API_KEY

If you receive a 415 error, set the data type to application/json (the same data type as in GPT-API requests) or add the header "Content-Type": "application/json".

In the request body specify:

{
  "prompt": "A close-up shot of a perfectly ripe red apple",
  "styleName": "HD-HQ"
}

If you want to earn money on the requests made by users of your software, add the soft_id parameter as well. Its value is the number shown in the "For Developers" section of the Telegram bot ClipCloud. For example, "soft_id": 1742.

You will receive a response like this:

{
  "success": true,
  "creation_id": "12345678-abcd-ef12-3456-7890abcdef12"
}

Save the creation_id value; you'll need it in the next request to obtain the result. This parameter is always unique per generation request, regardless of how many images were requested via count.

Immediately after that, the image starts generating. At any time you can check the generation progress by sending a GET request to:

https://clipcloud.clipai.pro/api/creation/GENERATION_ID?apikey=YOUR_API_KEY

If the image is still being generated, you'll get a response like:

{"success":true,"message":"In progress","status":"in_progress","creation_id":"12345678-abcd-ef12-3456-7890abcdef12"}

And once it has been generated:

{
  "success": true,
  "message": "Images processed succesfully",
  "creation_id": "12345678-abcd-ef12-3456-7890abcdef12",
  "cost": 2.2,
  "censored": 0,
  "results": [
    "https://clipcloud.clipai.pro/images/326432e4661c42d709432284c836d410b5.webp",
    "https://clipcloud.clipai.pro/images/c9436e4e57c1d9b2eb81b48d85a98a88c1.webp"
  ]
}

In the successful response you will receive temporary links for downloading the generated images. They are provided in WebP format, which offers good compression and is well suited both for web use and for almost any local use case.

For generating images for an article

If you are generating images or illustrations for an article (including when the text is written by another AI such as GPT), you can submit only the article title in the image-creation request. However, the result is usually better if you describe in detail what exactly should appear in the image. Doing this manually is obviously difficult. Therefore, if your software already connects to a neural network that writes text, we recommend first sending a request for image descriptions:

You are an assistant who gives the result of the task execution strictly in the specified form. Your goal is to select a prompt and parameters for generating images using another AI. To do this, you need to describe what and how should be depicted in the picture or photograph. At the same time, your entire output must be in English, regardless of the input language. Avoid using text on images or image requests where the neural network might add text, letters, or digits. Use high-quality styles if the image should contain, for example, a person or many different complex objects. Specify queries so that they should not generate prohibited content: eg NSFW. Use specific styles only if you feel it is necessary for this particular article. You have been given the title of the article or query: "Article name". You need to generate image count picture prompts, outputting the result as a single valid JSON array. Each element of the array must be a JSON object with the following structure: {"picture_number": 1, "query": "describe here what should be in the picture", "negative_prompt": "here describe what could theoretically appear with such a request, but at the same time should clearly not be in the picture according to your idea. This parameter is optional", "style": "select a style from: standard,smallHQ,HD-HQ,FullHD-HQ-h,FullHD-HQ-v,graffiti,illustration,oldphoto,aquarelle,pixel-art,pop-art,tilt-shift,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-512-768-v,HQ-640-1024-v"}

Thus, several tasks are solved at once:

• A quality description is written for each image.
• The image style is selected automatically.
• The request is in English, regardless of the language of the article title.
• If multiple images are required, each one will differ, just as when illustrations are manually selected for the article.

If you wish, you can edit the above prompt to suit your needs, for example, if it is more convenient for you not to work with a JSON response.

After that, immediately send the image-creation request, even if the article itself has not yet been generated or written; this lets you obtain the answer as quickly as possible when it is needed. Once the article is written or generated, download the generated images.

Here you can find specific examples of requests for creating images and retrieving the generated pictures.

Frequently Asked Questions

API Explorer

Send real requests to the ClipCloud API right from this page. Your API key is kept only in this browser tab (sessionStorage), is forgotten as soon as you close the tab, and is sent only to the ClipCloud API.