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

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

Щоб використовувати API, спочатку потрібно перейти на сторінку Sora Videos Generation API для подачі заявки на відповідну послугу. Після переходу на сторінку натисніть кнопку «Acquire», як показано на малюнку: Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, щоб запросити реєстрацію та вхід. Після входу або реєстрації ви автоматично повернетеся на поточну сторінку. При першій подачі заявки вам буде надано безкоштовний ліміт, який дозволяє безкоштовно використовувати цей API.

​
Основне використання

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

Ми можемо бачити, що тут ми налаштували заголовки запиту, включаючи:
  • accept: формат відповіді, який ви хочете отримати, тут вказано application/json, тобто формат JSON.
  • authorization: ключ для виклику API, який можна вибрати після подачі заявки.
Крім того, налаштовано тіло запиту, яке включає:
  • model: модель для генерації відео, основні з яких sora-2, sora-2-pro. Наразі sora-2 та sora-2-pro дозволяють самостійно вибирати параметри size, duration, де sora-2-pro підтримує тривалість 25 секунд, а sora-2 лише 10 або 15 секунд.
  • size: чіткість завдання на генерацію відео, доступні small, large.
  • image_urls: посилання на зображення або масив кодування Base64, які потрібно завантажити.
  • duration: тривалість завдання на генерацію відео, доступні 10s, 15s, 25s, наразі лише sora-2-pro підтримує 25s.
  • character_start/character_end: початкова та кінцева позиція персонажа на екрані (0-1), для контролю положення об’єкта.
  • orientation: орієнтація зображення, підтримує landscape, portrait, square.
  • prompt: підказка.
  • callback_url: URL для отримання результатів.
Після вибору ви можете помітити, що праворуч також згенеровано відповідний код, як показано на малюнку:

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

​
Завдання на генерацію відео з зображення

Якщо ви хочете створити завдання на генерацію відео з зображення, спочатку параметр 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": "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"
    }
  ]
}
Можна побачити, що згенерований ефект - це відео, створене на основі зображення, результат схожий на попередній.

​
Завдання на створення відео з персонажем

Якщо ви хочете створити відео з персонажем, спочатку параметр 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://filesystem.site/cdn/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4",
      "state": "succeeded"
    }
  ]
}
Можна побачити, що згенерований ефект - це відео з персонажем, результат схожий на попередній.

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

Оскільки час генерації 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, як показано на малюнку: Зміст наступне: 
```json
{
    "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, якщо виникає помилка, 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"
}

​
Висновок

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