> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Instrukcja integracji z Sora Videos Generation API > Sora Video Generation 集成指南 - XHuoAPI 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](https://api.xhuoapi.ai/documents/99a24421-2e22-4028-8201-e19cb834b67e). Po wejściu na stronę kliknij przycisk „Acquire”, jak pokazano na obrazku: ![](https://cdn.xhuoapi.ai/q6ytrc.png) 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: ```json theme={null} { "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: ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/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: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/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: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/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 | Parametr | Typ | Wymagany | Opis | | -------------- | ------- | -------- | ------------------------------------------------------------------------------------------- | | `version` | string | tak | Ustaw na `"2.0"` | | `prompt` | string | tak | Słowo kluczowe do generowania wideo | | `model` | string | nie | `sora-2` (domyślny) lub `sora-2-pro` | | `duration` | integer | nie | Długość wideo: `4` (domyślnie), `8`, `12` sekund | | `size` | string | nie | Rozdzielczość: `720x1280` (domyślnie), `1280x720`, `1024x1792`, `1792x1024` | | `image_urls` | array | nie | Tablica URL obrazów referencyjnych, używana tylko pierwsza grafika, rozmiar zgodny z `size` | | `callback_url` | string | nie | URL do asynchronicznego callbacku | ### Podstawowy przykład ```shell theme={null} curl -X POST 'https://api.xhuoapi.ai/v1/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: ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/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: ```javascript theme={null} const response = await fetch('https://api.xhuoapi.ai/v1/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: ```json theme={null} { "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.xhuoapi.ai/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): ```python theme={null} import requests url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/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 | Parametr | Version 1.0 | Version 2.0 | | --------------- | ------------------------------ | --------------------------------------- | | `version` | 1.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/](https://webhook.site/). Po wejściu na stronę otrzymujemy unikalny URL webhooka, np.: ![](https://cdn.xhuoapi.ai/cjjfly.png) 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: ![](https://cdn.xhuoapi.ai/0j7nra.png) Zawartość: ```json theme={null} { "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 ```json theme={null} { "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.