Przejdź do głównej treści
W tym dokumencie przedstawimy instrukcję integracji z Sora Videos Generation API, które umożliwia generowanie oficjalnych filmów Sora na podstawie niestandardowych parametrów wejściowych. API obsługuje dwa tryby wersji:
  • Version 1 (tryb klasyczny): obsługuje parametry duration (10/15/25 sekund), orientation (poziomy/pionowy), size (small/large rozdzielczość), obrazy referencyjne image_urls, link do postaci character_url itp.
  • Version 2 (tryb partnera): obsługuje parametry seconds (4/8/12 sekund), rozdzielczość pikselową size (np. 1280x720), obrazy referencyjne input_reference itp.

​
Proces aplikacji

Aby korzystać z API, należy najpierw złożyć wniosek o usługę na stronie Sora Videos Generation API. Po wejściu na stronę kliknij przycisk „Acquire”, jak pokazano na obrazku: Jeśli nie jesteś zalogowany lub zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania/rejestracji. Po zalogowaniu lub rejestracji wrócisz automatycznie do bieżącej strony. Przy pierwszym wniosku otrzymasz darmowy limit, dzięki któremu możesz korzystać z API bezpłatnie.

​
Podstawowe użycie (Version 1)

Na początek zapoznaj się z podstawowym sposobem użycia Version 1, polegającym na podaniu słowa kluczowego prompt, tablicy linków do obrazów referencyjnych image_urls oraz modelu model, aby otrzymać przetworzony wynik. Szczegóły poniżej:

Widzimy tutaj ustawienia nagłówków żądania (Request Headers), w tym:
  • accept: format odpowiedzi, tutaj ustawiony na application/json (format JSON).
  • authorization: klucz API do wywołania, który można wybrać z listy po złożeniu wniosku.
Dodatkowo ustawiono ciało żądania (Request Body), zawierające:
  • model: model generujący wideo, obsługujący sora-2 (tryb standardowy) oraz sora-2-pro (tryb HD). Model sora-2-pro obsługuje długość duration do 25 sekund, natomiast sora-2 tylko 10 lub 15 sekund.
  • size: rozdzielczość wideo, small to standardowa rozdzielczość, large to HD (tylko Version 1).
  • duration: długość wideo, obsługiwane wartości to 10, 15, 25 sekund (25 sekund tylko dla sora-2-pro, tylko Version 1).
  • orientation: orientacja obrazu, obsługiwane wartości to landscape (poziomo), portrait (pionowo) (tylko Version 1).
  • image_urls: tablica linków do obrazów referencyjnych, wykorzystywanych do generowania wideo z obrazów (tylko Version 1).
  • character_url: link do postaci, wideo nie może zawierać prawdziwych osób (tylko Version 1).
  • character_start/character_end: czas pojawienia się postaci w sekundach, zakres 1-3 sekund (tylko Version 1).
  • prompt: słowo kluczowe (wymagane).
  • callback_url: URL do asynchronicznego callbacku.
  • version: wersja API, "1.0" (domyślnie) lub "2.0".
Po wybraniu parametrów po prawej stronie wygenerowany zostanie odpowiedni kod, jak na obrazku:

Kliknij przycisk „Try”, aby przetestować. Jak widać na powyższym obrazku, otrzymaliśmy następujący wynik: 
{
  "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"
    }
  ]
}
W odpowiedzi znajduje się wiele pól, opis poniżej:
  • success: status zadania generowania wideo.
  • task_id: ID zadania generowania wideo.
  • trace_id: ID śledzenia zadania.
  • data: lista wyników zadania generowania wideo.
    • id: ID wygenerowanego wideo.
    • video_url: link do wygenerowanego wideo.
    • state: status zadania.
Widzimy, że otrzymaliśmy satysfakcjonujące informacje o wideo i wystarczy pobrać wygenerowany film Sora z linku w data. Jeśli chcesz wygenerować kod integracji, możesz go bezpośrednio skopiować, np. kod 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"
}'

​
Zadanie generowania wideo z obrazu (Version 1)

Aby wykonać zadanie generowania wideo z obrazu, należy przekazać parametr image_urls z linkami do obrazów referencyjnych, co pozwoli określić następujące:
  • image_urls: tablica linków do obrazów referencyjnych używanych do generowania wideo. Należy unikać przesyłania prawdziwych zdjęć osób, ponieważ może to spowodować niepowodzenie zadania.
Przykład wypełnienia:

Po wypełnieniu automatycznie wygenerowany zostanie kod:

Odpowiadający kod: 
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)
Po uruchomieniu od razu otrzymamy wynik: 
{
  "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"
    }
  ]
}
Widać, że efekt to generowanie wideo na podstawie obrazu, wynik podobny do powyższego.

​
Zadanie generowania wideo z postaci (Version 1)

Aby wykonać zadanie generowania wideo z postaci, należy przekazać parametr character_url z linkiem do filmu potrzebnego do stworzenia postaci. Należy pamiętać, że wideo nie może zawierać prawdziwych osób, w przeciwnym razie zadanie zakończy się niepowodzeniem. Można określić następujące:
  • character_url: link do filmu potrzebnego do stworzenia postaci, wideo nie może zawierać prawdziwych osób.
Przykład wypełnienia:

Po wypełnieniu automatycznie wygenerowany zostanie kod:

Odpowiadający kod: 
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)
Po uruchomieniu od razu otrzymamy wynik: 
{
  "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"
    }
  ]
}
Widać, że efekt to generowanie wideo z postaci, wynik podobny do powyższego.

​
Tryb Version 2.0

Oprócz trybu Version 1.0, API obsługuje także tryb Version 2.0, który można włączyć ustawiając parametr version na "2.0". Tryb Version 2.0 obsługuje krótsze długości wideo oraz kontrolę rozdzielczości na poziomie pikseli.

​
Opis parametrów Version 2.0

ParametrTypWymaganyOpis
versionstringtakUstaw na "2.0"
promptstringtakSłowo kluczowe do generowania wideo
modelstringniesora-2 (domyślny) lub sora-2-pro
durationintegernieDługość wideo: 4 (domyślnie), 8, 12 sekund
sizestringnieRozdzielczość: 720x1280 (domyślnie), 1280x720, 1024x1792, 1792x1024
image_urlsarraynieTablica URL obrazów referencyjnych, używana tylko pierwsza grafika, rozmiar zgodny z size
callback_urlstringnieURL do asynchronicznego callbacku

​
Podstawowy przykład

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"
}'
Odpowiadający kod 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)
Odpowiadający kod 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);
Format odpowiedzi jest taki sam jak w 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"
    }
  ]
}

​
Użycie obrazów referencyjnych (Version 2.0)

W trybie Version 2.0 można przekazać parametr image_urls z obrazem referencyjnym, który będzie użyty do generowania wideo (tylko pierwsza grafika): 
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)
Uwaga: rozmiar obrazu referencyjnego powinien być zgodny z parametrem size, np. dla size równego 1280x720 obraz powinien mieć rozmiar 1280×720.

​
Porównanie parametrów Version 1.0 i Version 2.0

ParametrVersion 1.0Version 2.0
version1.0 (domyślnie)2.0
prompt✅✅
model✅ sora-2 / sora-2-pro✅ sora-2 / sora-2-pro
duration✅ 10/15/25 sekund✅ 4/8/12 sekund
orientation✅ landscape/portrait❌
size✅ small/large✅ 720x1280/1280x720/1024x1792/1792x1024
image_urls✅ wiele obrazów referencyjnych✅ tylko pierwszy obraz
character_url✅❌
callback_url✅✅

​
Asynchroniczny callback

Ponieważ generowanie wideo przez Sora Videos Generation API trwa stosunkowo długo (około 1-2 minut), a długotrwałe oczekiwanie na odpowiedź HTTP może powodować nadmierne zużycie zasobów systemowych, API oferuje wsparcie dla asynchronicznego callbacku. Proces jest następujący: klient wysyła żądanie z dodatkowym polem callback_url. Po wysłaniu żądania API natychmiast zwraca odpowiedź zawierającą task_id – ID zadania. Po zakończeniu generowania wideo wynik zostanie przesłany metodą POST w formacie JSON na wskazany callback_url, zawierający również task_id, co pozwala na powiązanie wyników z zadaniem. Poniżej przykład działania. Webhook callback to usługa HTTP zdolna do odbierania żądań. Programista powinien zastąpić ją własnym serwerem HTTP. Dla wygody demonstracji użyto publicznej strony Webhook: https://webhook.site/. Po wejściu na stronę otrzymujemy unikalny URL webhooka, np.: Skopiuj ten URL, np. https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa, i użyj go jako callback_url. Następnie ustaw pole callback_url na ten URL i wypełnij pozostałe parametry, jak na obrazku:

Po kliknięciu „Run” otrzymamy natychmiast wynik: 
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
Po chwili na stronie https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa zobaczymy wynik generowania wideo: Zawartość: 
{
    "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"
        }
    ]
}
Widzimy pole task_id, a pozostałe pola są podobne do wcześniejszych, co pozwala powiązać wynik z zadaniem.

​
Obsługa błędów

Podczas wywoływania API, w przypadku błędów, API zwróci odpowiedni kod i komunikat błędu, np.:
  • 400 token_mismatched: Nieprawidłowe żądanie, prawdopodobnie brak lub błędne parametry.
  • 400 api_not_implemented: Nieprawidłowe żądanie, prawdopodobnie brak lub błędne parametry.
  • 401 invalid_token: Nieautoryzowany, nieprawidłowy lub brakujący token autoryzacyjny.
  • 429 too_many_requests: Zbyt wiele żądań, przekroczono limit.
  • 500 api_error: Błąd wewnętrzny serwera.

​
Przykład odpowiedzi błędu

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

​
Podsumowanie

W tym dokumencie poznali Państwo sposób użycia Sora Videos Generation API, które umożliwia generowanie wideo na podstawie słów kluczowych oraz obrazów referencyjnych. Mamy nadzieję, że instrukcja pomoże w łatwej integracji i korzystaniu z API. W razie pytań prosimy o kontakt z zespołem wsparcia technicznego.