API + Нейронные сети

API нейросети Sora Images открывает пользователям удобную возможность для генерации изображения непосредственно внутри любых своих проектов. Это может быть чат-бот для мессенджеров, таких как Telegram, стороннее приложение или интернет-сервис. Несмотря на то, что возможности нейросети Sora охватывают генерацию не только картинок, но и видеороликов, данная инструкция посвящена исключительно созданию изображений. Если же вы хотите узнать подробнее о генерации видео с помощью Sora, обратитесь к отдельному руководству по API.

Если вы решили использовать возможности Sora Images посредством API Yes Ai, то вам необходимо предварительно получить специальный авторизационный токен. Подробную инструкцию по его получению вы найдете в нашем руководстве.

Прежде чем приступать к созданию собственного приложения с использованием нашего API, стоит протестировать весь доступный функционал Sora Images через телеграм-бота @yes_ai_bot. Также советуем тщательно ознакомиться с возможностями самой нейросети — этому вопросу посвящена отдельная статья, с которой вы можете ознакомиться.

Ключевые положения:

• Любые косвенные или прямые ссылки на контент, маркированный пометкой «18+» или иным образом относящийся к категории NSFW, недопустимы. Необходимо заранее проверять запросы на наличие запрещенных слов и выражений, прежде чем направлять их к нашему API.

• Нейросеть Sora Images обладает возможностью создавать изображения по текстовым описаниям (промтам), заданным на разных языках, включая русский язык.

• Система позволяет задать от одного до десяти изображений в качестве визуальных референсов-ориентиров, которые будут учитываться при создании нового контента.

• При использовании API с добавлением хотя бы одной картинки-референса пользователю необходимо в обязательном порядке указать промт — описание конкретных действий или изменений, которые нужно применить к отображённым на исходном материале объектам.

• Sora генерирует изображения в трёх доступных пропорциях сторон картинки: 1:1, 2:3 и 3:2.

• После каждого обращения API выдаёт результирующие изображения в количестве от одного до четырёх. В большинстве сценариев пользователи получат именно 4 готовых изображения; меньшее их число встречается значительно реже.

Обратите внимание! В настоящее время для работы с API Sora Images действуют определенные ограничения по количеству одновременно выполняемых задач. Эти ограничения зависят от того, какой пакет услуг подключен к вашему аккаунту:

• Пакет Demo позволяет поставить в очередь не более 1 задачи одновременно.

• Пакет Micro ограничен 2 задачами в очереди.

• Пакет Start предусматривает очередь до 3 задач.

• Пакет Standard допускает не более 5 задач одновременно в очереди.

• Пакет VIP предоставляет максимальное значение — до 10 задач в очереди.

Если при использовании API Sora Images у вас возникнут дополнительные вопросы или вам потребуется расширение установленных лимитов, пожалуйста, обращайтесь в нашу службу технической поддержки по адресу: @yes_ai_support.

Как формулировать задания через промты (без использования референсов)

Пример составления запроса для создания изображений в сервисе Sora Images без референс-материалов

curl -X POST https://api.yesai.su/v2/sora/generations

-H "Authorization: Bearer <token>"

-H "Content-Type: application/json"

-d '{

"prompt": "текст вашего промпта на любом языке",

"style":"2,3",

"dimesions":"2:3"

}'

Описание параметров:

Параметр style = '', '0', '1' или '2,3,4' (необязательный): Задает стилистическое оформление. По умолчанию используется значение "0", то есть стиль не применяется. Доступны следующие варианты выбора:

0 – без заданного стиля

1 – случайный выбор стиля

2,3,4 и т.п. — выбор конкретного тематического стиля:

2 – Midjourney

3 – Стимпанк (Steampunk)

4 – Киберпанк (Cyberpunk)

5 – Аниме (Anime)

6 – Логотип (Logo)

7 – Фото (Photo)

8 – Изображение (Image)

9 – Кино (Cinema)

10 – Иллюстрация (Illustration)

11 – Ужасы (Horror)

12 – Детализированный (Detailed)

13 – Космос (Space)

14 – Готика (Gothic)

15 – Сюрреализм (Surrealism)

16 – Реализм (Realism)

17 – Фэнтези (Fantasy)

18 – Научная фантастика (Sci-Fi)

19 – Арт-фэнтези (FantasyArt)

20 – Комиксы (ComicBook)

21 – Пиксель-арт (PixelArt)

22 – 3D графика

23 – Линейный рисунок (LineArt)

24 – Оригами (Origami)

25 – Изометрия (Isometric)

26 – Неонпанк (NeonPunk)

27 – Аниме-премиум (PrimeAnime)

28 – Акварель (Watercolor)

29 – Поп-арт (Pop art)

30 – Каваии (Kawaii)

31 – Минимализм (Minimalism)

32 – Ретро футуризм (RetroFutur)

33 – Антиутопия (Dystopian)

34 – Реклама (Advertising)

35 – Ренессанс (Renaissance)

36 – Биомеханика (Biomechanical)

37 – Футуризм (Futuristic)

38 – Арт-деко (Art deco)

39 – Кубизм (Cubism)

40 – Мода (Fashion)

41 – RPG

42 – Диско (Disco)

43 – Архитектура (Architecture)

44 – Роскошь (Luxury)

45 – Кибернетика (Cybernetic)

46 – Ретро-кибер (RetroCyber)

47 – Биокибер (BioCyber)

48 – Сказочный (FairyTale)

49 – Пин-ап (Pin-up)

50 – Сияние (Shining)

51 – Сдвиг цветов (Color shift)

Параметр prompt = '' (обязательный): описывает задание, сформулированное пользователем. Язык описания может быть любым.

Параметр dimensions = '2:3' (необязательный): устанавливает пропорции получаемого изображения. По умолчанию установлено соотношение сторон 1:1 (квадрат). Возможные варианты:

• 1:1 – квадратное изображение

• 2:3 – вертикальное изображение

• 3:2 – горизонтальное изображение

Обратите внимание: по умолчанию нейросеть Sora Images часто генерирует изображения с приглушенными оттенками и недостаточной яркостью. Чтобы устранить такую особенность алгоритма, наши специалисты разработали специальный стиль обработки с названием "Shining", которому присвоен индекс "50". Настоятельно рекомендуем использовать этот стиль по умолчанию при выполнении заданий.

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

Пример успешного ответа при постановке задачи:
['success' => true, 'message' => 'OK', 'results' => ['generation_data' => [ ... ]]], 200

Как подать задание с помощью референсов

Разбираем на примере, как создавать изображения в Sora Images с использованием референсов

curl -X POST https://api.yesai.su/v2/sora/generations

-H "Authorization: Bearer <token>"

-H "Content-Type: application/json"

-d '{

"prompt": "текст вашего промпта на любом языке",

"style":"2,3",

"dimesions":"2:3"

"references_urls":["https://yoururl.com/image1.jpeg","https://yoururl.com/image2.jpeg"]

}'

Параметры:

references_urls = [] (необязательно, массив ссылок на референсные изображения, минимум 1, максимум 10)

В это поле нужно вставлять от 1 до 10 прямых ссылок, ведущих на изображения в форматах jpg, jpeg или png, которые служат референсами для создания изображений нейросетью. Ко всем заданиям также обязательно следует добавлять подробные текстовые описания-промты, поясняющие, какое именно изображение требуется сгенерировать.

Перечень типичных ошибок:

['success' => false, 'message' => 'MODEL_ID_IS_EMPTY'], 400
['success' => false, 'message' => 'MODEL_ID_NOT_VALID'], 400
['success' => false, 'message' => 'ID_IS_EMPTY'], 400
['success' => false, 'message' => 'ID_NOT_VALID'], 400
['success' => false, 'message' => 'TYPE_IS_EMPTY'], 400
['success' => false, 'message' => 'TYPE_NOT_VALID'], 400
['success' => false, 'message' => 'STYLE_IS_EMPTY'], 400
['success' => false, 'message' => 'STYLE_NOT_VALID'], 400
['success' => false, 'message' => 'PROMPT_IS_EMPTY'], 400
['success' => false, 'message' => 'PROMPT_NOT_VALID'], 400
['success' => false, 'message' => 'REFERENCES_URLS_IS_EMPTY'], 400
['success' => false, 'message' => 'REFERENCES_URLS_NOT_VALID'], 400
['success' => false, 'message' => 'DIMENSIONS_IS_EMPTY'], 400
['success' => false, 'message' => 'DIMENSIONS_NOT_VALID'], 400
['success' => false, 'message' => 'UNAUTHORIZED'], 401
['success' => false, 'message' => 'ID_NOT_FOUND'], 404
['success' => false, 'message' => 'USER_HAS_BEEN_BANNED'], 409
['success' => false, 'message' => 'USER_HAS_BEEN_DELETED'], 409
['success' => false, 'message' => 'NOT_ENOUGH_RPOINTS'], 409
['success' => false, 'message' => 'PROMPT_NSFW_WORDS'], 409
['success' => false, 'message' => 'PROMPT_EN_NSFW_WORDS'], 409
['success' => false, 'message' => 'STYLE_LIMIT_EXCEEDED'], 409
['success' => false, 'message' => 'TASK_LIMIT_EXCEEDED'], 409
['success' => false, 'message' => 'TASK_IS_NOT_COMPLETED'], 409
['success' => false, 'message' => 'TOO_MANY_REQUESTS'], 429
['success' => false, 'message' => 'INTERNAL_SERVER_ERROR'], 500

Как получить готовые изображения через Sora Images API?

Когда вы отправляете запрос на генерацию через API Sora Images, сервис возвращает вам индивидуальный идентификатор задания. Именно этот ID используется далее для получения готовых результатов, которыми выступают ссылки на скачивание изображений. Обычно их количество составляет от одной до четырёх ссылок на одно задание.

Специалисты сервиса советуют первый раз проверять готовность генерации не ранее, чем через полминуты после отправки запроса. Ранее этого срока изображения просто не успеют сгенерироваться. Последующие проверки лучше всего проводить с интервалом от 10 до 15 секунд. Это оптимальный промежуток, позволяющий сервису завершить генерацию без лишней нагрузки и обеспечить комфортный пользовательский опыт.

GET https://api.yesai.su/v2/sora/generations/{id}/batch
headers: { Content-Type: application/json, Authorization: Bearer }

Образец запроса, который позволяет проверить статус выполнения задачи с использованием родительского идентификатора (ID).

curl -X GET https://api.yesai.su/v2/sora/generations/{id}/batch

-H "Authorization: Bearer <token>"

-H "Content-Type: application/json"

Параметры:
{id} = 12345 (обязательно, id задания)

Успех:
['success' => true, 'message' => 'OK', 'results' => ['generations_data' => [ ... ]]], 200

Список возможных ошибок:
['success' => false, 'message' => 'ID_IS_EMPTY'], 400
['success' => false, 'message' => 'ID_NOT_VALID'], 400
['success' => false, 'message' => 'UNAUTHORIZED'], 401
['success' => false, 'message' => 'ID_NOT_FOUND'], 404
['success' => false, 'message' => 'USER_HAS_BEEN_BANNED'], 409
['success' => false, 'message' => 'USER_HAS_BEEN_DELETED'], 409
['success' => false, 'message' => 'TOO_MANY_REQUESTS'], 429
['success' => false, 'message' => 'INTERNAL_SERVER_ERROR'], 500

Перечень возможных статусов задания представлен ниже:

• "status": 0 ("status_description":"in queue"): задание ожидает своей очереди на выполнение. Требуемое действие – ожидание.

• "status": 1 ("status_description":"in progress"): в данный момент идет работа над заданием. Нужно некоторое время подождать, пока работа не будет завершена.

• "status": 2 ("status_description":"completed"): задание выполнено успешно. Исходя из этого статуса, вы можете приступать к обработке доступных результатов. По мере их готовности будут появляться новые дочерние задания (примерный временной интервал добавления таких заданий составляет от 3 до 10 секунд).

• "status": 3 ("status_description":"rejected with error"): задание отклонено из-за возникшей ошибки. В таком случае обязательно ознакомьтесь с подробным комментарием, поясняющим причину, в полях "comment_ru" и "comment_en".

• "status": 4 ("status_description":"rejected due to timeout"): срок выполнения задания вышел, и оно было автоматически отклонено системой. Рекомендуется повторно отправить задание.

Как разобрать JSON-данные, полученные через API от Sora Images при пакетной генерации (batch) изображений

Рассмотрим конкретный пример ответа API, который возвращается при запросе статуса задания по идентификатору родительского задания.

{
"success": true,// данные успешно получены
"message": "OK",
"results": {
"generations_data": {
"info": {
"count": 4, // количество изображений в задании
"max_id": 457,
"limit_offset": 0,
"limit_count": 20,
"sort_field": "id",
"sort_order": 1,
"id_offset": 2147483647
},
"data": [
{
"id": 454, // id первого задания в пачке (это ID родительского задания)
"user_id": 1234567890, // id пользователя, подавшего задание
"tariff_id": 30, // id тарифа пользователя, подавшего задание, 30 - VIP
"model_id": 1,
"type": 53,
"styles": [], // массив стилей, использованных для генерации изображений
"settings": {
"model_alias": "sora_images",
"sora_dimensions": "1:1",
"sora_references_urls": [
"https://api.yesai.su/tests/face1.jpeg",
"https://api.yesai.su/tests/face2.jpeg"
]
},
"child_ids": [ // список дочерних заданий, от 1 до 3 штук
455,
456,
457
],
"parent_id": 0,
"result_url": "https://yesai.su/files/sora/generations/1234567890_174741769...", ссылка на скачивание первой картинки из пачки заданий
"result_type": "image",
"result_data": {
"image_width": 1024,
"image_height": 1024,
"image_mime_type": "image/png"
},
"comment_ru": "", // комментарий к заданию на русском языке, будет заполнен только при ошибке генерации со статуосм 3
"comment_en": "", // комментарий к заданию на английском языке, будет заполнен только при ошибке генерации со статуосм 3
"accounting": {
"total_cost": 0.7,
"spent_points": 0,
"spent_rpoints": 0.7, // стоимость генерации этого изображения из пачки в монетах, все генерации в Sora Images оцениваются в монетах
"spent_repost_points": 0,
"spent_balance": 0,
"spent_rbalance": 0,
"remaining_points": 1832.87225,
"remaining_rpoints": 9809.445587639999, // остаток монет на балансе заказчика в помент выполнения задания
"remaining_repost_points": 0,
"remaining_balance": 0,
"remaining_rbalance": 22106.49481
},
"language": "",
"prompt": "текст вашего промта", // текст промта, по которому сгенерировано это изображение
"prompt_en": "",
"prompt_language": "",
"status": 2, // статус задания, 2 - успешное выполнение генерации
"status_description": "completed", // текстовое описание статусы задания
"start_at": 1747417691, // время начала выполнения задания в формате Unixtime
"finish_at": 1747417696, // время завершения выполнения задания в формате Unixtime
"created_at": 1747417518, // время подачи задания в формате Unixtime
"updated_at": 1747417792,
"deleted_at": 0
},
{
// здесь будет находиться блок с данными о второй генерации в пачке. Блоки JSON идентичны тем, которые были описаны выше.
},
{
// здесь будет находиться блок с данными о третьей генерации в пачке. Блоки JSON идентичны тем, которые были описаны выше.
},
{
// здесь будет находиться блок с данными о четвертой генерации в пачке. Блоки JSON идентичны тем, которые были описаны выше.
}
]
}
}
}

Если при обращении к API сервиса Sora Images вы получили JSON-ответ, содержащий только одну ссылку в разделе "result_url", это означает, что остальные изображения еще находятся в процессе генерации. Для получения оставшихся ссылок следует выполнять повторные запросы каждые 10–15 секунд. При этом мы рекомендуем ограничиться 7 попытками. Если через 50–70 секунд после первой ссылки новые изображения не появились, значит, нейросеть не смогла создать дополнительные картинки. Аналогично иногда нейросеть может выдать вместо стандартных 4 изображений только 2 или 3.

В случае невозможности выполнения генерации, поле статуса запроса ("status") будет содержать цифру 3, свидетельствующую об ошибке. Тогда важно сообщить клиенту разъяснение причин ошибки, которое представлено в описании блоков "comment_ru" (на русском языке) и "comment_en" (на английском языке). Такой подход позволяет предупредить повторные ошибки, заранее информируя пользователей о потенциальных проблемах.

Наиболее распространенной причиной отказа в генерации является нарушение правил использования сервиса Sora Images. Особенно строго запрещена генерация NSFW-контента ("Not Safe For Work" — неподобающий контент). Для предотвращения блокировки API обязательно уведомите клиентов о запрете отправки подобных запросов. Игнорирование этих рекомендаций может привести к ограничению доступа к API-платформе.

Как происходит обработка заданий на генерацию изображений в Sora Images, отправленных через API Yes Ai?

После того как вы через API отправили запрос на создание изображений в нейросети Sora Images, успешно выполненное задание предоставит вам индивидуальные ссылки. По этим ссылкам вам станут доступны изображения форматов PNG либо JPG. Однако обратите внимание, что данные файлы хранятся на сервере всего 60 минут. Поэтому, не откладывая, сразу скачайте полученные картинки на собственный сервер.

Если у вас возникнут любые дополнительные вопросы, служба технической поддержки оперативно поможет решить их в мессенджере Telegram: @yes_ai_support.