Przejdź do głównej treści
W tym artykule przedstawimy sposób integracji Sora Videos Generation API, które pozwala na generowanie oficjalnych filmów Sora poprzez wprowadzenie niestandardowych parametrów.

​
Proces aplikacji

Aby skorzystać z API, należy najpierw przejść do strony Sora Videos Generation API i złożyć wniosek o odpowiednią usługę. Po wejściu na stronę, kliknij przycisk „Acquire”, jak pokazano na obrazku: Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować. Po zalogowaniu lub rejestracji automatycznie wrócisz na bieżącą stronę. Podczas pierwszej aplikacji otrzymasz darmowy limit, który pozwala na bezpłatne korzystanie z tego API.

​
Podstawowe użycie

Najpierw zapoznaj się z podstawowym sposobem użycia, czyli wprowadzeniem słowa kluczowego prompt, tablicy linków do obrazów image_urls oraz modelu model, aby uzyskać przetworzony wynik. Szczegóły są następujące:

Możemy zobaczyć, że ustawiliśmy nagłówki żądania, w tym:
  • accept: format odpowiedzi, który chcemy otrzymać, tutaj wpisujemy application/json, czyli format JSON.
  • authorization: klucz do wywołania API, który można wybrać z rozwijanej listy po złożeniu wniosku.
Dodatkowo ustawiono ciało żądania, w tym:
  • model: model generujący wideo, głównie sora-2, sora-2-pro, obecnie sora-2 i sora-2-pro pozwalają na samodzielny wybór parametrów size i duration, przy czym sora-2-pro obsługuje wideo o długości 25s, a sora-2 tylko 10 i 15 sekund.
  • size: rozdzielczość generowanego wideo, dostępne są small i large.
  • image_urls: linki do referencyjnych obrazów lub tablica kodów Base64, które należy przesłać.
  • duration: długość generowanego wideo, dostępne są 10s, 15s, 25s, obecnie tylko sora-2-pro obsługuje 25s.
  • character_start/character_end: pozycje postaci na ekranie (0-1), używane do kontrolowania pozycji głównego obiektu.
  • orientation: orientacja obrazu, obsługuje landscape, portrait, square.
  • prompt: słowo kluczowe.
  • callback_url: URL, na który mają być zwracane wyniki.
Po dokonaniu wyboru, można zauważyć, że po prawej stronie wygenerowano odpowiedni kod, jak pokazano na obrazku:

Klikając przycisk „Try”, można przeprowadzić test, jak pokazano na powyższym obrazku, uzyskując 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"
    }
  ]
}
Wynik zwrotny zawiera wiele pól, które są opisane poniżej:
  • success, status zadania generowania wideo.
  • task_id, ID zadania generowania wideo.
  • trace_id, ID śledzenia zadania generowania wideo.
  • data, lista wyników zadania generowania wideo.
    • id, ID wideo zadania generowania wideo.
    • video_url, link do wideo zadania generowania wideo.
    • state, status zadania generowania wideo.
Możemy zobaczyć, że otrzymaliśmy satysfakcjonujące informacje o wideo, wystarczy, że uzyskamy link do wideo z data, aby pobrać wygenerowane wideo Sora. Jeśli chcesz wygenerować odpowiedni kod do integracji, możesz go po prostu skopiować, na przykład kod CURL wygląda następująco: 
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 obrazów

Jeśli chcesz zrealizować zadanie generowania wideo z obrazów, najpierw parametr image_urls musi zawierać linki do referencyjnych obrazów, aby można było określić następujące treści:
  • image_urls: tablica linków do referencyjnych obrazów używanych w tym zadaniu generowania wideo.
Przykład wypełnienia jest następujący:

Po wypełnieniu automatycznie wygenerowano kod, jak pokazano poniżej:

Odpowiedni 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)
Klikając „Uruchom”, można zauważyć, że natychmiast otrzymasz wynik, jak poniżej: 
{
  "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"
    }
  ]
}
Można zauważyć, że wygenerowany efekt to wideo stworzone na podstawie obrazu, a wynik jest podobny do powyższego.

​
Zadanie generowania wideo z postacią

Jeśli chcesz wygenerować wideo z postacią, najpierw parametr character_url musi zawierać link do wideo potrzebnego do stworzenia postaci, pamiętaj, że w wideo nie mogą pojawiać się prawdziwi ludzie, w przeciwnym razie operacja zakończy się niepowodzeniem, można określić następujące treści:
  • character_url: link do wideo potrzebnego do stworzenia postaci, pamiętaj, że w wideo nie mogą pojawiać się prawdziwi ludzie, w przeciwnym razie operacja zakończy się niepowodzeniem.
Przykład wypełnienia poniżej:

Po wypełnieniu automatycznie wygenerowano kod jak poniżej:

Odpowiedni 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": "kot biegnący nad rzeką",
    "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 kliknięciu uruchomienia, można zauważyć, że natychmiast otrzymuje się wynik, jak poniżej: 
{
  "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"
    }
  ]
}
Można zauważyć, że wygenerowany efekt to wideo stworzone na podstawie postaci, a wynik jest podobny do powyższego.

​
Asynchroniczny callback

Ponieważ czas generowania wideo przez API Sora Videos Generation jest stosunkowo długi, wynosi około 1-2 minut, jeśli API nie odpowiada przez dłuższy czas, żądanie HTTP będzie utrzymywać połączenie, co prowadzi do dodatkowego zużycia zasobów systemowych, dlatego to API oferuje również wsparcie dla asynchronicznych callbacków. Cały proces wygląda następująco: klient inicjuje żądanie, dodatkowo określając pole callback_url, po wysłaniu żądania API natychmiast zwraca wynik, zawierający pole task_id, które reprezentuje aktualne ID zadania. Po zakończeniu zadania, wynik generowania wideo zostanie wysłany do określonego przez klienta callback_url w formie POST JSON, w tym również zawierając pole task_id, dzięki czemu wyniki zadania można powiązać za pomocą ID. Poniżej przyjrzymy się, jak dokładnie to działa na przykładzie. Najpierw, callback Webhook to usługa, która może odbierać żądania HTTP, deweloperzy powinni zastąpić ją URL swojego serwera HTTP. W tym celu, dla wygody demonstracji, użyjemy publicznej strony przykładowej Webhook https://webhook.site/, otwierając tę stronę można uzyskać URL Webhook, jak pokazano na obrazku: Skopiuj ten URL, aby użyć go jako Webhook, przykładowy URL to https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa. Następnie możemy ustawić pole callback_url na powyższy URL Webhook, a także wypełnić odpowiednie parametry, szczegóły jak na obrazku:

Po kliknięciu uruchomienia, można zauważyć, że natychmiast otrzymuje się wynik, jak poniżej: 
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
Po chwili możemy na https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa zaobserwować wynik generowania piosenki, jak pokazano na obrazku: Treść jest następująca: 
```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"
        }
    ]
}
Można zauważyć, że w wynikach znajduje się pole task_id, a pozostałe pola są podobne do powyższych, dzięki czemu można powiązać zadania.

​
Obsługa błędów

Podczas wywoływania API, jeśli wystąpi błąd, API zwróci odpowiedni kod błędu i informacje. Na przykład:
  • 400 token_mismatched: Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
  • 400 api_not_implemented: Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
  • 401 invalid_token: Nieautoryzowany, nieprawidłowy lub brakujący token autoryzacyjny.
  • 429 too_many_requests: Zbyt wiele żądań, przekroczono limit szybkości.
  • 500 api_error: Błąd wewnętrzny serwera, coś poszło nie tak na serwerze.

​
Przykład odpowiedzi błędu

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

​
Wnioski

Dzięki temu dokumentowi zrozumieli Państwo, jak korzystać z API Sora Videos Generation, które umożliwia generowanie wideo na podstawie wprowadzonych słów kluczowych oraz zdjęć referencyjnych. Mamy nadzieję, że ten dokument pomoże Państwu lepiej zintegrować i korzystać z tego API. W razie jakichkolwiek pytań prosimy o kontakt z naszym zespołem wsparcia technicznego.