> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Інструкція з інтеграції Sora Videos Generation API > Sora Video Generation 集成指南 - XHuoAPI У цій статті описано інструкцію з інтеграції Sora Videos Generation API, за допомогою якого можна генерувати офіційні відео Sora, вводячи власні параметри. Цей API підтримує два режими: * **Version 1 (класичний режим)**: підтримує параметри `duration` (10/15/25 секунд), `orientation` (горизонтальна/вертикальна орієнтація), `size` (small/large роздільна здатність), референсні зображення `image_urls`, посилання на персонажа `character_url` тощо. * **Version 2 (режим партнерів)**: підтримує `seconds` (4/8/12 секунд), роздільну здатність на рівні пікселів `size` (наприклад, 1280x720), референсні зображення `input_reference` тощо. ## Процес подачі заявки Щоб користуватися API, спочатку потрібно подати заявку на відповідний сервіс на сторінці [Sora Videos Generation API](https://api.xhuoapi.ai/documents/99a24421-2e22-4028-8201-e19cb834b67e). Після переходу на сторінку натисніть кнопку «Acquire», як показано на зображенні: ![](https://cdn.xhuoapi.ai/q6ytrc.png) Якщо ви ще не увійшли або не зареєстровані, система автоматично перенаправить вас на сторінку входу або реєстрації. Після входу або реєстрації ви повернетесь на поточну сторінку. При першій подачі заявки надається безкоштовний ліміт для використання API. ## Основне використання (Version 1) Спочатку ознайомтеся з базовим способом використання Version 1: вводяться підказка `prompt`, масив посилань на референсні зображення `image_urls` та модель `model`, після чого отримується оброблений результат. Деталі наведені нижче:

Тут ми налаштували заголовки запиту (Request Headers), зокрема: * `accept`: формат відповіді, який ви хочете отримати, тут вказано `application/json` (формат JSON). * `authorization`: ключ для виклику API, який можна вибрати зі списку після подачі заявки. Також налаштовано тіло запиту (Request Body): * `model`: модель для генерації відео, підтримуються `sora-2` (стандартний режим) та `sora-2-pro` (режим HD). Модель `sora-2-pro` підтримує `duration` до 25 секунд, тоді як `sora-2` — лише 10 або 15 секунд. * `size`: роздільна здатність відео, `small` — стандартна, `large` — HD (тільки Version 1). * `duration`: тривалість відео, підтримується 10, 15, 25 секунд (25 секунд лише для `sora-2-pro`, тільки Version 1). * `orientation`: орієнтація відео, підтримується `landscape` (горизонтальна) та `portrait` (вертикальна) (тільки Version 1). * `image_urls`: масив посилань на референсні зображення для генерації відео з картинки (тільки Version 1). * `character_url`: посилання на персонажа, у відео не повинно бути реальних людей (тільки Version 1). * `character_start`/`character_end`: час появи персонажа у відео в секундах, різниця 1-3 секунди (тільки Version 1). * `prompt`: підказка (обов’язковий параметр). * `callback_url`: URL для асинхронного зворотного виклику. * `version`: версія API, `"1.0"` (за замовчуванням) або `"2.0"`. Після вибору параметрів праворуч з’являється відповідний код, як показано на зображенні:

Натисніть кнопку «Try», щоб протестувати запит. У прикладі нижче отримано такий результат: ```json theme={null} { "success": true, "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33", "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01", "data": [ { "id": "sora-2:task_01k7770rgsevxsmtpbn7xnm5gh", "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k7770rgsevxsmtpbn7xnm5gh%2Ftask_01k7770rgsevxsmtpbn7xnm5gh_genid_0bf958d3-cae7-4298-b7b6-99ae439a1ea6_25_10_10_14_06_975715%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A30%3A38Z&se=2025-10-16T13%3A30%3A38Z&sks=b&skt=2025-10-10T12%3A30%3A38Z&ske=2025-10-16T13%3A30%3A38Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=8ebb0df1-a278-4e2e-9c20-f2d373479b3a&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=jigY6Z5qp8%2BTXYobaW0EAJ4%2Fbx6G7t6V1P0iyDeUq48%3D&az=oaivgprodscus", "state": "succeeded" } ] } ``` Пояснення полів відповіді: * `success`: статус завдання генерації відео. * `task_id`: ID завдання генерації відео. * `trace_id`: ID трасування запиту. * `data`: список результатів завдання генерації відео. * `id`: ID відео завдання. * `video_url`: посилання на згенероване відео. * `state`: статус завдання. Отже, отримано потрібну інформацію про відео, і можна завантажити згенероване відео за посиланням у полі `data`. Якщо потрібно згенерувати код для інтеграції, його можна скопіювати напряму. Наприклад, CURL-запит: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/sora/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "size": "large", "duration": 15, "orientation": "landscape", "prompt": "cat running on the river", "model": "sora-2" }' ``` ## Генерація відео з картинки (Version 1) Для генерації відео з картинки потрібно передати параметр `image_urls` з масивом посилань на референсні зображення. Важливо: не передавайте реальні фото з обличчями людей, інакше завдання може не виконатися. Приклад заповнення:

Після заповнення автоматично генерується код:

Приклад коду: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "size": "large", "duration": 15, "orientation": "landscape", "prompt": "cat running on the river", "model": "sora-2", "image_urls": ["https://cdn.xhuoapi.ai/11wfp4.png"] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Після запуску одразу отримуємо результат: ``` { "success": true, "task_id": "dd392ff0-dcb7-4c7a-afd0-9bd4f65c803a", "trace_id": "04fd151c-e942-4c1c-a6ab-9a1b1fe54172", "data": [ { "id": "sora-2:task_01k777af4hfmg9g7yfvwsc6zws", "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k777af4hfmg9g7yfvwsc6zws%2Ftask_01k777af4hfmg9g7yfvwsc6zws_genid_92bae0c5-1703-4a5f-9d9f-c9ed2f9e7176_25_10_10_14_12_924695%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A37%3A32Z&se=2025-10-16T13%3A37%3A32Z&sks=b&skt=2025-10-10T12%3A37%3A32Z&ske=2025-10-16T13%3A37%3A32Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=5j4dibeaSsDmEka5c%2B9CKHZhRPdqfClQ0tIh03TWXsM%3D&az=oaivgprodscus", "state": "succeeded" } ] } ``` Отже, результат — відео, згенероване за допомогою картинки, подібне до попереднього. ## Генерація відео з персонажем (Version 1) Для генерації відео з персонажем потрібно передати параметр `character_url` з посиланням на відео, яке використовується для створення персонажа. Відео не повинно містити реальних людей, інакше завдання не виконається. Параметри: * `character_url`: посилання на відео для створення персонажа, без реальних людей. Приклад заповнення:

Після заповнення автоматично генерується код:

Приклад коду: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "size": "small", "duration": 10, "orientation": "landscape", "prompt": "cat running on the river", "character_url": "https://cdn.xhuoapi.ai/pdidf5.mp4", "model": "sora-2", "character_end": 3, "character_start": 1 } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Після запуску одразу отримуємо результат: ``` { "success": true, "task_id": "d9bf5461-29b5-47fd-be90-1fe9197df259", "trace_id": "b7992643-9207-40d6-956b-7577728acc67", "data": [ { "id": "sora-2:task_01k8ykrztefavaypw6xanw305b", "video_url": "https://filesystem.site/cdn/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4", "state": "succeeded" } ] } ``` Отже, отримано відео з персонажем, подібне до попередніх прикладів. ## Режим Version 2.0 Окрім Version 1.0, API підтримує режим Version 2.0, який активується встановленням параметра `version` в `"2.0"`. Цей режим підтримує коротші відео та керування роздільною здатністю на рівні пікселів. ### Пояснення параметрів Version 2.0 | Параметр | Тип | Обов’язковий | Опис | | -------------- | ------- | ------------ | -------------------------------------------------------------------------------------------------------------------- | | `version` | string | Так | Встановити `"2.0"` | | `prompt` | string | Так | Підказка для генерації відео | | `model` | string | Ні | `sora-2` (за замовчуванням) або `sora-2-pro` | | `duration` | integer | Ні | Тривалість відео: `4` (за замовчуванням), `8`, `12` секунд | | `size` | string | Ні | Роздільна здатність: `720x1280` (за замовчуванням), `1280x720`, `1024x1792`, `1792x1024` | | `image_urls` | array | Ні | Масив URL референсних зображень, використовується лише перше зображення, розмір повинен відповідати параметру `size` | | `callback_url` | string | Ні | URL для асинхронного зворотного виклику | ### Базовий приклад ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/sora/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "version": "2.0", "prompt": "cat running on the river", "model": "sora-2", "duration": 8, "size": "1280x720" }' ``` Відповідний код на Python: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "version": "2.0", "prompt": "cat running on the river", "model": "sora-2", "seconds": 8, "size": "1280x720" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Відповідний код на JavaScript: ```javascript theme={null} const response = await fetch('https://api.xhuoapi.ai/v1/sora/videos', { method: 'POST', headers: { 'accept': 'application/json', 'authorization': 'Bearer {token}', 'content-type': 'application/json' }, body: JSON.stringify({ version: '2.0', prompt: 'cat running on the river', model: 'sora-2', seconds: 8, size: '1280x720' }) }); const data = await response.json(); console.log(data); ``` Формат відповіді аналогічний Version 1: ```json theme={null} { "success": true, "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33", "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01", "data": [ { "id": "c0cc8dad-0954-421f-be8d-02eb063b3263", "video_url": "https://platform.cdn.xhuoapi.ai/sora/xxxxx.mp4", "state": "succeeded" } ] } ``` ### Використання референсних зображень (Version 2.0) У режимі Version 2.0 можна передати параметр `image_urls` з референсним зображенням для керування генерацією відео (використовується лише перше зображення): ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/sora/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "version": "2.0", "prompt": "a person walking through a beautiful garden", "model": "sora-2", "duration": 4, "size": "1280x720", "image_urls": ["https://cdn.xhuoapi.ai/11wfp4.png"] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` > **Увага**: розмір референсного зображення повинен відповідати параметру `size`. Наприклад, якщо `size` дорівнює `1280x720`, то розмір зображення має бути 1280×720. ### Порівняння параметрів Version 1.0 та Version 2.0 | Параметр | Version 1.0 | Version 2.0 | | --------------- | ---------------------- | --------------------------------------- | | `version` | 1.0 (за замовчуванням) | 2.0 | | `prompt` | ✅ | ✅ | | `model` | ✅ sora-2 / sora-2-pro | ✅ sora-2 / sora-2-pro | | `duration` | ✅ 10/15/25 секунд | ✅ 4/8/12 секунд | | `orientation` | ✅ landscape/portrait | ❌ | | `size` | ✅ small/large | ✅ 720x1280/1280x720/1024x1792/1792x1024 | | `image_urls` | ✅ кілька зображень | ✅ лише перше зображення | | `character_url` | ✅ | ❌ | | `callback_url` | ✅ | ✅ | ## Асинхронний зворотний виклик Оскільки генерація відео через Sora Videos Generation API займає приблизно 1-2 хвилини, а HTTP-запит може довго тримати з’єднання, що призводить до додаткових витрат ресурсів, API підтримує асинхронний зворотний виклик. Процес: клієнт при відправці запиту вказує додатково поле `callback_url`. Після отримання запиту API одразу повертає результат із полем `task_id` — ідентифікатором завдання. Коли завдання завершується, результат у форматі POST JSON надсилається на вказаний `callback_url`, де також міститься `task_id` для зв’язку результату із завданням. Розглянемо приклад. Webhook callback — це сервіс, який приймає HTTP-запити. Розробник повинен замінити URL на свій сервер. Для демонстрації використано публічний сервіс [https://webhook.site/](https://webhook.site/), на якому можна отримати унікальний Webhook URL, як показано на зображенні: ![](https://cdn.xhuoapi.ai/cjjfly.png) Скопіюйте цей URL, наприклад `https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa`, і використовуйте як Webhook. Далі встановіть поле `callback_url` у цей Webhook URL та заповніть інші параметри, як показано:

Після запуску отримуємо результат: ``` { "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea" } ``` Через деякий час на сторінці `https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa` можна побачити результат генерації відео, як на зображенні: ![](https://cdn.xhuoapi.ai/0j7nra.png) Вміст: ```json theme={null} { "success": true, "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea", "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2", "data": [ { "id": "sora-2:task_01k777hjrbfrgs2060q5zvf2a5", "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k777hjrbfrgs2060q5zvf2a5%2Ftask_01k777hjrbfrgs2060q5zvf2a5_genid_b8e2e5d1-a579-49ca-a21c-cb3869685cce_25_10_10_14_15_147334%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A38%3A49Z&se=2025-10-16T13%3A38%3A49Z&sks=b&skt=2025-10-10T12%3A38%3A49Z&ske=2025-10-16T13%3A38%3A49Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=p4aMqXqkP%2FI1IhOVGCB9JL8vUUvfNBBF12ESpKhKXOk%3D&az=oaivgprodscus", "state": "succeeded" } ] } ``` У відповіді є поле `task_id`, інші поля аналогічні попереднім. За цим полем можна зв’язати результат із завданням. ## Обробка помилок При виклику API у разі помилки повертаються відповідні коди та повідомлення. Наприклад: * `400 token_mismatched`: некоректний запит, можливо, відсутні або неправильні параметри. * `400 api_not_implemented`: некоректний запит, можливо, відсутні або неправильні параметри. * `401 invalid_token`: неавторизований, недійсний або відсутній токен авторизації. * `429 too_many_requests`: перевищено ліміт запитів. * `500 api_error`: внутрішня помилка сервера. ### Приклад відповіді з помилкою ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Висновок У цій документації ви дізналися, як користуватися Sora Videos Generation API для генерації відео за допомогою підказок та референсних зображень. Сподіваємося, що цей документ допоможе вам легко інтегрувати та використовувати API. Якщо у вас виникнуть питання, будь ласка, звертайтеся до нашої технічної підтримки.