Документация API ClipCloud

REST API для генерации изображений нейросетью: один POST-запрос создаёт картинку в любом из 35 готовых стилей, один GET-запрос скачивает результат. Бесплатный ежедневный лимит на каждом ключе, платный режим для объёмов и реферальная программа 10% для разработчиков ПО.

Основная информация

API ClipCloud очень простой. Всего три шага:

Авторизация

Каждый запрос должен содержать ваш API-ключ, который всегда начинается с clip-. Получить ключ можно в Telegram-боте @clipcloudbot или управлять им в личном кабинете. Два равнозначных способа передать ключ:

• Query-параметр: ?apikey=clip-... (используется в примерах ниже);
• HTTP-заголовок: Authorization: Bearer clip-...

Стоимость и баланс: кредит 🖼️

Цены и поле cost считаются в кредитах ClipCloud, которые обозначаются 🖼️ — это не доллары. Идея та же, что у токенов в текстовых ИИ-API: одна небольшая единица учёта, в которой удобно сравнивать цену совершенно разных картинок. Курс фиксированный:

Счётчиков два, и их легко перепутать — кредиты это не то же самое, что бесплатные картинки:

Типичные цены за картинку:

Опубликованные цены ориентировочные. Чтобы узнать точную цену конкретного запроса, отправьте его с check_cost: true: сервер вернёт цену и не запустит генерацию и ничего не спишет.

Генерация изображений

Если вы планируете интегрировать ClipCloud в своё ПО на несколько пользователей, мы рекомендуем интегрировать только стандартную генерацию (по стилю).

Генерация изображенияСтандартная, по стилю

Сгенерируйте изображение, выбрав стиль. Это рекомендованный способ для всех.Стандартная генерация картинок по стилю, которая рекомендуется для использования всем пользователям сервиса.

В результате данного запроса вы получите ID начатой генерации. Он будет один, даже если вы укажете значение count > 1. Данный ID будет необходим для дальнейшего получения результата создания картинки или картинок.

Обязательны лишь параметры prompt и styleName в теле запроса, а также apikey в URL запроса.

POST-запрос, формат данных: application/json (как, например, и в API GPT).

Query-параметры

Параметры тела запроса

Поддерживаемые стили (значения styleName)

Обратите внимание: для апскейл-стилей (например, HQ-4K-h, HQ-1920-1024-h, HQ-1024-1920-v) ширина и высота, возвращаемые GET /api/styles, могут не соответствовать финальному размеру изображения, т.к. улучшением их качества (апскейлом) занимается отдельная нейронная сеть. При этом работа с такими стилями совершенно не отличается от использования других стилей.

Ответы

{
  "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" }

Пример

▶ Попробовать в API Explorer

Расширенная, с доп. параметрами

Получение результата

GET-запрос. В URL запроса: ваш API-ключ и ID генерации, полученный ранее в ответе на запрос генерации изображения. В ответе: ссылка/ссылки на сгенерированные изображения (по 1 ссылке на каждое изображение).

Path-параметры

Ответы

{
  "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." }

Пример

▶ Попробовать в API Explorer

Прочие запросы

В этой категории расположены прочие запросы, которые могут быть полезны (но совсем не обязательны) в программах в некоторых случаях: проверка баланса API-ключа и получение доступных стилей.

Проверка баланса

GET-запрос. В URL запроса: ваш API-ключ. В ответе: информация о балансе этого API-ключа.

Ответы

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

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

Пример

Доступные стили

GET-запрос. В URL запроса: ваш API-ключ. В ответе: актуальная информация о существующих стилях.

Более подробную информацию о стилях, с понятными названиями и описанием, вы можете найти в таблице стилей выше.

Ответы

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

Пример

Примеры использования API

Для генерации картинок по заранее известному запросу

Данный API крайне простой для добавления и использования. Для создания картинки и получения результата вам необходимо выполнить лишь:

• Один POST-запрос с двумя параметрами;
• Один GET-запрос с одним параметром.

Даже если вы используете минимальное количество параметров, как и указано здесь, качество изображений будет отличным в большинстве случаев.

Предположим, вам необходимо сгенерировать одну картинку на запрос «A close-up shot of a perfectly ripe red apple». При этом вы хотите получить качественное и реалистичное изображение, поэтому выбрали стиль HD-HQ (полный список стилей - в таблице styleName). Вам необходимо отправить POST-запрос по URL:

https://clipcloud.clipai.pro/api/creation?apikey=ВАШ_API_КЛЮЧ

Если у вас появляется ошибка 415, используйте тип данных application/json (такой же тип используется, например, в запросах с API GPT) либо добавьте заголовок "Content-Type": "application/json".

В теле запроса укажите:

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

Если вы хотите заработать на запросах пользователей вашей программы, не забудьте также добавить параметр soft_id, значением которого будет число из раздела «Для разработчиков» Telegram-бота ClipCloud. Например, "soft_id": 1742.

Вы получите ответ вида:

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

Из ответа сохраните значение creation_id: он пригодится в следующем запросе на получение результата. Данный параметр всегда один на каждый запрос генерации, вне зависимости от того, сколько изображений было запрошено параметром count.

Сразу после этого картинка начнёт генерироваться. В любой момент вы можете проверить процесс генерации, отправив GET-запрос по URL:

https://clipcloud.clipai.pro/api/creation/ID_ГЕНЕРАЦИИ?apikey=ВАШ_API_КЛЮЧ

Если картинка ещё генерируется, то вы получите ответ вида:

{"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"
  ]
}

В ответе на данный запрос, при успешной генерации, вы получите временные ссылки на скачивание сгенерированных изображений. Они будут в формате WebP, который обеспечивает хорошее сжатие и отлично подходит как для использования в интернете, так и для локального использования практически в любых задачах.

Для генерации картинок к статье

Если вы генерируете картинки или иллюстрации к статье (в том числе если текст пишет другой ИИ: например, GPT), вы можете отправлять лишь название статьи в запрос на создание картинок. Однако зачастую результат будет лучше, если подробно описать в запросе, что именно должно быть на изображении. Очевидно, это сложно сделать вручную. Поэтому, если в вашем ПО уже подключена какая-либо нейронная сеть для написания текста, мы рекомендуем сначала отправить запрос на описание картинок:

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: "Название статьи". You need to generate необходимое количество изображений 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"}

Таким образом, будет решено сразу несколько задач:

• Будет написано качественное описание для каждого изображения.
• Будет автоматически выбран стиль изображения.
• Запрос будет на английском языке, вне зависимости от того, на каком языке написано название статьи.
• Если необходимо несколько изображений, то каждое из них будет разным, как и при ручном подборе иллюстраций к статье.

При желании вы можете отредактировать указанный выше запрос по своему усмотрению: например, если вам удобнее работать не с JSON-ответом.

После этого сразу же отправляйте запрос на создание изображений, даже если сама статья ещё не сгенерирована или не написана: так можно будет максимально быстро получить ответ, как только он станет необходим. И уже после написания/генерации статьи скачайте сгенерированные изображения.

Здесь можно посмотреть конкретные примеры запросов на создание и получение созданных картинок.

Частые вопросы

API Explorer

Отправляйте реальные запросы к API ClipCloud прямо с этой страницы. Ваш API-ключ хранится только в этой вкладке браузера (sessionStorage), забывается сразу при её закрытии и отправляется только на API ClipCloud.