Перейти до основного вмісту
У цій статті описано інструкцію з інтеграції 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. Після переходу на сторінку натисніть кнопку «Acquire», як показано на зображенні: Якщо ви ще не увійшли або не зареєстровані, система автоматично перенаправить вас на сторінку входу або реєстрації. Після входу або реєстрації ви повернетесь на поточну сторінку. При першій подачі заявки надається безкоштовний ліміт для використання 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», щоб протестувати запит. У прикладі нижче отримано такий результат: 
{
  "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-запит: 
curl -X POST 'https://api.acedata.cloud/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 з масивом посилань на референсні зображення. Важливо: не передавайте реальні фото з обличчями людей, інакше завдання може не виконатися. Приклад заповнення:

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

Приклад коду: 
import requests

url = "https://api.acedata.cloud/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.acedata.cloud/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: посилання на відео для створення персонажа, без реальних людей.
Приклад заповнення:

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

Приклад коду: 
import requests

url = "https://api.acedata.cloud/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.acedata.cloud/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

ПараметрТипОбов’язковийОпис
versionstringТакВстановити "2.0"
promptstringТакПідказка для генерації відео
modelstringНіsora-2 (за замовчуванням) або sora-2-pro
durationintegerНіТривалість відео: 4 (за замовчуванням), 8, 12 секунд
sizestringНіРоздільна здатність: 720x1280 (за замовчуванням), 1280x720, 1024x1792, 1792x1024
image_urlsarrayНіМасив URL референсних зображень, використовується лише перше зображення, розмір повинен відповідати параметру size
callback_urlstringНіURL для асинхронного зворотного виклику

​
Базовий приклад

curl -X POST 'https://api.acedata.cloud/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: 
import requests

url = "https://api.acedata.cloud/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: 
const response = await fetch('https://api.acedata.cloud/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: 
{
  "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.acedata.cloud/sora/xxxxx.mp4",
      "state": "succeeded"
    }
  ]
}

​
Використання референсних зображень (Version 2.0)

У режимі Version 2.0 можна передати параметр image_urls з референсним зображенням для керування генерацією відео (використовується лише перше зображення): 
import requests

url = "https://api.acedata.cloud/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.acedata.cloud/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.0Version 2.0
version1.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/, на якому можна отримати унікальний Webhook URL, як показано на зображенні: Скопіюйте цей 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 можна побачити результат генерації відео, як на зображенні: Вміст: 
{
    "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: внутрішня помилка сервера.

​
Приклад відповіді з помилкою

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Висновок

У цій документації ви дізналися, як користуватися Sora Videos Generation API для генерації відео за допомогою підказок та референсних зображень. Сподіваємося, що цей документ допоможе вам легко інтегрувати та використовувати API. Якщо у вас виникнуть питання, будь ласка, звертайтеся до нашої технічної підтримки.