Sora Videos Generation API 연동 안내

이 문서에서는 Sora Videos Generation API 연동 방법을 소개합니다. 이 API를 통해 사용자 정의 매개변수를 입력하여 Sora 공식 영상을 생성할 수 있습니다. 본 API는 두 가지 버전 모드를 지원합니다:

Version 1(클래식 모드): duration(10/15/25초), orientation(가로/세로), size(small/large 해상도), 참고 이미지 image_urls, 캐릭터**###** character_url 등의 매개변수를 지원합니다.
Version 2(파트너 모드): seconds(4/8/12초), 픽셀 단위 해상도 size(예: 1280x720), 참고 이미지 input_reference 등의 매개변수를 지원합니다.

신청 절차

API를 사용하려면 먼저 Sora Videos Generation API 해당 페이지에서 서비스를 신청해야 합니다. 페이지에 접속한 후, 「Acquire」 버튼을 클릭하세요. 아래 그림과 같습니다:

로그인 또는 회원가입이 되어 있지 않으면 자동으로 로그인 페이지로 이동하며, 로그인 후 자동으로 현재 페이지로 돌아옵니다. 최초 신청 시 무료 할당량이 제공되어 무료로 API를 사용할 수 있습니다.

기본 사용법 (Version 1)

먼저 Version 1의 기본 사용법을 이해해야 합니다. prompt(프롬프트), 참고 이미지 링크 배열 image_urls, 그리고 모델 model을 입력하면 처리된 결과를 얻을 수 있습니다. 구체적인 내용은 다음과 같습니다:

여기서 Request Headers를 설정했습니다:

accept: 원하는 응답 형식을 지정하며, 여기서는 application/json (JSON 형식)으로 설정했습니다.
authorization: API 호출을 위한 키로, 신청 후 드롭다운에서 선택할 수 있습니다.

또한 Request Body를 설정했습니다:

model: 영상 생성 모델로, sora-2(표준 모드)와 sora-2-pro(고화질 모드)를 지원합니다. sora-2-pro는 25초 영상 duration을 지원하며, sora-2는 10초, 15초만 지원합니다.
size: 영상 해상도로, small은 표준 해상도, large는 HD 해상도(Version 1 전용)입니다.
duration: 영상 길이로, 10초, 15초, 25초를 지원하며 25초는 sora-2-pro만 지원합니다(Version 1 전용).
orientation: 화면 방향으로, landscape(가로), portrait(세로)를 지원합니다(Version 1 전용).
image_urls: 참고 이미지 링크 배열로, 이미지 기반 영상 생성에 사용됩니다(Version 1 전용).
character_url: 캐릭터**###** 링크로, 영상 내 실제 인물이 포함되면 안 됩니다(Version 1 전용).
character_start/character_end: 캐릭터 등장 시작 및 종료 초 단위, 1~3초 범위(Version 1 전용).
prompt: 프롬프트(필수).
callback_url: 비동기 콜백 결과를 받을 URL.
version: API 버전, "1.0"(기본) 또는 "2.0".

선택 후 오른쪽에 해당 코드가 생성됩니다. 아래 그림과 같습니다:

「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: 영상 생성 작업 상태.

만족스러운 영상 정보를 얻었으며, 결과의 data 내 영상 링크를 통해 생성된 Sora 영상을 받을 수 있습니다. 또한 대응하는 연동 코드를 생성할 수 있으며, 예를 들어 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"
}'

이미지 기반 영상 생성 작업 (Version 1)

이미지 기반 영상 작업을 하려면 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"
    }
  ]
}

생성된 결과가 이미지 기반 영상 생성임을 확인할 수 있으며, 결과는 위와 유사합니다.

캐릭터 생성 영상 작업 (Version 1)

캐릭터 생성 영상 작업을 하려면 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": "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)

실행하면 즉시 다음과 같은 결과를 얻을 수 있습니다:

{
  "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"
    }
  ]
}

생성된 결과가 캐릭터 생성 영상임을 확인할 수 있으며, 결과는 위와 유사합니다.

Version 2.0 모드

앞서 설명한 Version 1.0 모드 외에도 본 API는 Version 2.0 모드를 지원하며, version 매개변수를 "2.0"으로 설정하면 활성화됩니다. Version 2.0 모드는 더 짧은 영상 길이와 픽셀 단위 해상도 제어를 지원합니다.

Version 2.0 매개변수 설명

매개변수	타입	필수 여부	설명
`version`	string	예	`"2.0"`으로 설정
`prompt`	string	예	영상 생성 프롬프트
`model`	string	아니오	`sora-2`(기본) 또는 `sora-2-pro`
`duration`	integer	아니오	영상 길이: `4`(기본), `8`, `12`초
`size`	string	아니오	해상도: `720x1280`(기본), `1280x720`, `1024x1792`, `1792x1024`
`image_urls`	array	아니오	참고 이미지 URL 배열, 첫 번째 이미지만 사용, 이미지 크기는 `size`와 일치해야 함
`callback_url`	string	아니오	비동기 콜백 URL

기본 예제

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"
}'

해당 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)

해당 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);

반환 결과 형식은 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"
    }
  ]
}

참고 이미지 사용 (Version 2.0)

Version 2.0 모드에서는 image_urls 매개변수로 참고 이미지를 전달하여 영상 생성을 유도할 수 있습니다(첫 번째 이미지 한 장만 사용):

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)

주의: 참고 이미지 크기는 size 매개변수와 일치해야 합니다. 예를 들어 size가 1280x720일 경우, 참고 이미지 크기도 1280×720이어야 합니다.

Version 1.0과 Version 2.0 매개변수 비교

매개변수	Version 1.0	Version 2.0
`version`	1.0(기본)	2.0
`prompt`	✅	✅
`model`	✅ sora-2 / sora-2-pro	✅ sora-2 / sora-2-pro
`duration`	✅ 10/15/25초	✅ 4/8/12초
`orientation`	✅ landscape/portrait	❌
`size`	✅ small/large	✅ 720x1280/1280x720/1024x1792/1792x1024
`image_urls`	✅ 다수 참고 이미지	✅ 첫 번째 이미지만 사용
`character_url`	✅	❌
`callback_url`	✅	✅

비동기 콜백

Sora Videos Generation API는 영상 생성에 약 1~2분이 소요되므로, API가 장시간 응답하지 않으면 HTTP 요청이 계속 연결되어 시스템 자원을 낭비할 수 있습니다. 이를 위해 본 API는 비동기 콜백을 지원합니다. 전체 흐름은 다음과 같습니다: 클라이언트가 요청 시 callback_url 필드를 추가 지정하면, API는 즉시 task_id를 포함한 결과를 반환합니다. 작업 완료 후 생성된 영상 결과를 POST JSON 형식으로 클라이언트가 지정한 callback_url로 전송하며, task_id 필드도 포함되어 작업 결과를 ID로 연동할 수 있습니다. 아래 예제로 구체적인 사용법을 살펴봅니다. 먼저 Webhook 콜백은 HTTP 요청을 받을 수 있는 서비스여야 하며, 개발자는 직접 구축한 HTTP 서버 URL로 교체해야 합니다. 여기서는 편의를 위해 공개 Webhook 사이트 https://webhook.site/ 를 사용합니다. 사이트를 열면 Webhook URL을 얻을 수 있습니다. 아래 그림과 같습니다:

이 URL을 복사하여 Webhook으로 사용할 수 있습니다. 예시 URL은 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에서 생성된 영상 결과를 확인할 수 있습니다. 아래 그림과 같습니다:

내용은 다음과 같습니다:

{
    "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"
}

결론

이 문서를 통해 Sora Videos Generation API를 사용하여 프롬프트와 참고 이미지를 입력해 영상을 생성하는 방법을 이해하셨습니다. 본 문서가 API 연동과 사용에 도움이 되길 바랍니다. 문의 사항이 있으면 언제든지 기술 지원팀에 연락해 주십시오.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

프록시

고급

Sora Videos Generation API 연동 안내

신청 절차

기본 사용법 (Version 1)

이미지 기반 영상 생성 작업 (Version 1)

캐릭터 생성 영상 작업 (Version 1)

Version 2.0 모드

Version 2.0 매개변수 설명

기본 예제

참고 이미지 사용 (Version 2.0)

Version 1.0과 Version 2.0 매개변수 비교

비동기 콜백

오류 처리

오류 응답 예시

결론

​신청 절차

​기본 사용법 (Version 1)

​이미지 기반 영상 생성 작업 (Version 1)

​캐릭터 생성 영상 작업 (Version 1)

​Version 2.0 모드

​Version 2.0 매개변수 설명

​기본 예제

​참고 이미지 사용 (Version 2.0)

​Version 1.0과 Version 2.0 매개변수 비교

​비동기 콜백

​오류 처리

​오류 응답 예시

​결론

신청 절차

기본 사용법 (Version 1)

이미지 기반 영상 생성 작업 (Version 1)

캐릭터 생성 영상 작업 (Version 1)

Version 2.0 모드

Version 2.0 매개변수 설명

기본 예제

참고 이미지 사용 (Version 2.0)

Version 1.0과 Version 2.0 매개변수 비교

비동기 콜백

오류 처리

오류 응답 예시

결론