Перейти к основному содержанию
В этой статье будет представлена инструкция по интеграции 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 по ссылке на видео из результата 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, представляющем текущий идентификатор задачи. Когда задача завершена, результат сгенерированного видео будет отправлен на указанный клиентом 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 на указанный выше URL Webhook, одновременно заполнив соответствующие параметры, конкретное содержание показано на изображении:

Нажав “Запустить”, можно сразу получить результат, как показано ниже: 
{
  "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. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку.