Інструкція з інтеграції API генерації відео Sora

У цьому документі буде представлено інструкцію з інтеграції API генерації відео Sora, за допомогою якого можна вводити користувацькі параметри для створення офіційних відео Sora. Цей API підтримує два режими версій:

Версія 1 (класичний режим): підтримує duration (10/15/25 секунд), orientation (горизонтальний/вертикальний), size (малий/великий) чіткості, посилання на зображення image_urls, відео персонажа character_url та інші параметри.
Версія 2 (партнерський режим): підтримує seconds (4/8/12 секунд), піксельну роздільну здатність size (наприклад, 1280x720), посилання на зображення input_reference та інші параметри.

Процес подачі заявки

Щоб використовувати API генерації відео Sora, спочатку перейдіть до консолі Ace Data Cloud, щоб отримати ваш API Token, зберігши його для подальшого використання.

Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, щоб запросити реєстрацію та вхід, після чого ви будете автоматично повернені на цю сторінку. Один API Token дозволяє викликати всі послуги платформи, не потрібно окремо подавати заявку на кожну послугу. Перший запит на отримання токена надає безкоштовний ліміт, щоб ви могли безкоштовно протестувати; якщо ліміт вичерпано, ви можете поповнити загальний баланс в консолі.

📘 Повна документація: API генерації відео Sora →

Основне використання (Версія 1)

Спочатку ознайомтеся з основним способом використання Версії 1, який полягає у введенні підказки prompt, масиву посилань на зображення image_urls та моделі model, щоб отримати оброблений результат, конкретний зміст наведено нижче:

Ми бачимо, що тут ми налаштували заголовки запиту, включаючи:

accept: формат відповіді, який ви хочете отримати, тут вказано application/json, тобто формат JSON.
authorization: ключ для виклику API, після подачі заявки ви можете вибрати його зі списку.

Також налаштовано тіло запиту, яке включає:

model: модель для генерації відео, підтримує sora-2 (стандартний режим) та sora-2-pro (висока чіткість). При цьому sora-2-pro підтримує duration для відео тривалістю 25 секунд, тоді як sora-2 підтримує лише 10, 15 секунд.
size: чіткість відео, small - стандартна чіткість, large - HD чіткість (тільки Версія 1).
duration: тривалість відео, підтримує 10, 15, 25 секунд, з яких 25 секунд підтримується лише sora-2-pro (тільки Версія 1).
orientation: напрямок кадру, підтримує landscape (горизонтальний), portrait (вертикальний) (тільки Версія 1).
image_urls: масив посилань на зображення, використовується для генерації відео (тільки Версія 1).
character_url: посилання на відео персонажа, у відео не можуть з’являтися реальні люди (тільки Версія 1).
character_start/character_end: час появи персонажа в секундах, діапазон від 1 до 3 секунд (тільки Версія 1).
prompt: підказка (обов’язково).
callback_url: URL для асинхронного зворотного виклику результату.
async: необов’язково, якщо встановити true, інтерфейс негайно поверне task_id, не потрібно надавати callback_url, потім через відповідний інтерфейс запиту завдань можна опитувати для отримання результату.
version: версія API, "1.0" (за замовчуванням) або "2.0".

Після вибору ви можете помітити, що праворуч також згенеровано відповідний код, як показано на малюнку:

Натисніть кнопку «Спробувати», щоб провести тестування, як показано на малюнку, ми отримали наступний результат:

{
  "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://platform.cdn.acedata.cloud/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, статус завдання генерації відео на даний момент.

Ми отримали задовільну інформацію про відео, нам потрібно лише отримати згенероване відео Sora за адресою посилання на відео в 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"
}'

Завдання генерації відео з зображення (Версія 1)

Якщо ви хочете виконати завдання генерації відео з зображення, спочатку параметр image_urls повинен містити посилання на зображення, щоб можна було вказати наступний зміст:

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": "кіт, що біжить по річці",
    "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://platform.cdn.acedata.cloud/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"
    }
  ]
}

Можна побачити, що згенерований ефект - це відео, створене з зображення, результат схожий на вищезазначене.

Завдання згенерування відео персонажа (Версія 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": "кіт, що біжить по річці",
    "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://platform.cdn.acedata.cloud/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4",
      "state": "succeeded"
    }
  ]
}

Можна побачити, що згенерований ефект - це відео, створене з персонажем, результат схожий на вищезазначене.

Режим Версія 2.0

Окрім вищезазначеного режиму Версія 1.0, цей API також підтримує режим Версія 2.0, активуючи його, встановивши параметр version на "2.0". Режим Версія 2.0 підтримує коротший час відео та контроль роздільної здатності на рівні пікселів.

Опис параметрів Версії 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 для асинхронного зворотного виклику

Основний приклад

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": "кіт, що біжить по річці",
  "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": "кіт, що біжить по річці",
    "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: 'кіт, що біжить по річці',
    model: 'sora-2',
    seconds: 8,
    size: '1280x720'
  })
});
const data = await response.json();
console.log(data);

Формат повернення результату такий же, як у Версії 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"
    }
  ]
}

Використання зображення для посилання (Версія 2.0)

У режимі Версія 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": "людина, що йде через красивий сад",
    "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.

Порівняння параметрів Версії 1.0 та Версії 2.0

Параметр	Версія 1.0	Версія 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`	✅ ландшафтний/портрет	❌
`size`	✅ малий/великий	✅ 720x1280/1280x720/1024x1792/1792x1024
`image_urls`	✅ кілька зображень для посилання	✅ використовується лише перше зображення
`character_url`	✅	❌
`callback_url`	✅	✅

Асинхронний зворотний виклик

Оскільки час генерації відео через API Sora Videos Generation відносно тривалий, приблизно 1-2 хвилини, якщо API довго не відповідає, HTTP запит буде підтримувати з’єднання, що призводить до додаткових витрат системних ресурсів, тому цей API також підтримує асинхронний зворотний виклик. Загальний процес: коли клієнт ініціює запит, додатково вказується поле callback_url, після ініціації API запиту API відразу повертає результат, що містить інформацію про поле task_id, яке представляє поточний ID завдання. Коли завдання завершено, результат генерації відео буде надіслано на вказаний клієнтом callback_url у форматі POST JSON, в якому також міститься поле task_id, таким чином результати завдання можна пов’язати за ID. Далі ми розглянемо приклад, щоб зрозуміти, як це працює. По-перше, Webhook зворотний виклик - це служба, яка може приймати HTTP запити, розробники повинні замінити на URL свого HTTP сервера. Для зручності демонстрації використовується публічний сайт з прикладом Webhook https://webhook.site/, відкривши цей сайт, ви отримаєте URL Webhook, як показано на малюнку:

Скопіюйте цей URL, і ви зможете використовувати його як Webhook, приклад тут: https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa. Далі ми можемо налаштувати поле 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://platform.cdn.acedata.cloud/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, якщо виникає помилка, 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. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Проксі

Advanced

Coding

Інструкція з інтеграції API генерації відео Sora

Процес подачі заявки

Основне використання (Версія 1)

Завдання генерації відео з зображення (Версія 1)

Завдання згенерування відео персонажа (Версія 1)

Режим Версія 2.0

Опис параметрів Версії 2.0

Основний приклад

Використання зображення для посилання (Версія 2.0)

Порівняння параметрів Версії 1.0 та Версії 2.0

Асинхронний зворотний виклик

Обробка помилок

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

Висновок

​Процес подачі заявки

​Основне використання (Версія 1)

​Завдання генерації відео з зображення (Версія 1)

​Завдання згенерування відео персонажа (Версія 1)

​Режим Версія 2.0

​Опис параметрів Версії 2.0

​Основний приклад

​Використання зображення для посилання (Версія 2.0)

​Порівняння параметрів Версії 1.0 та Версії 2.0

​Асинхронний зворотний виклик

​Обробка помилок

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

​Висновок

Процес подачі заявки

Основне використання (Версія 1)

Завдання генерації відео з зображення (Версія 1)

Завдання згенерування відео персонажа (Версія 1)

Режим Версія 2.0

Опис параметрів Версії 2.0

Основний приклад

Використання зображення для посилання (Версія 2.0)

Порівняння параметрів Версії 1.0 та Версії 2.0

Асинхронний зворотний виклик

Обробка помилок

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

Висновок