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 등의 매개변수를 지원합니다.

신청 절차

Sora Videos Generation API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API Token을 받아야 합니다. 이를 보관해 두십시오.

로그인 또는 등록이 되어 있지 않은 경우 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 요청합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다. 하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스마다 별도로 신청할 필요가 없습니다. 처음 신청 시 무료 한도가 제공되어 무료로 체험할 수 있습니다; 한도가 부족할 경우 콘솔에서 일반 잔액을 충전할 수 있습니다.

📘 전체 문서: Sora Videos Generation API →

기본 사용법(Version 1)

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

여기서 요청 헤더를 설정한 것을 볼 수 있습니다:

accept: 어떤 형식의 응답 결과를 받고 싶은지, 여기서는 application/json으로 JSON 형식을 입력합니다.
authorization: API 호출을 위한 키로, 신청 후 직접 드롭다운에서 선택할 수 있습니다.

또한 요청 본문을 설정했습니다:

model: 비디오를 생성하는 모델로, sora-2(표준 모드)와 sora-2-pro(고화질 모드)를 지원합니다. 이 중 sora-2-pro는 duration이 25초인 비디오를 지원하며, 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.
async: 선택 사항으로, true로 설정하면 인터페이스가 즉시 task_id를 반환하며, callback_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://platform.cdn.acedata.cloud/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": "강에서 뛰는 고양이",
    "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://platform.cdn.acedata.cloud/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"
    }
  ]
}

생성된 효과는 이미지에서 비디오를 생성한 것이며, 결과는 위와 유사합니다.

캐릭터 생성 비디오 작업 (버전 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": "강에서 뛰는 고양이",
    "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://platform.cdn.acedata.cloud/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4",
      "state": "succeeded"
    }
  ]
}

생성된 효과는 캐릭터 생성 비디오이며, 결과는 위와 유사합니다.

버전 2.0 모드

위의 버전 1.0 모드 외에도, 이 API는 버전 2.0 모드를 지원하며, version 매개변수를 "2.0"으로 설정하면 활성화됩니다. 버전 2.0 모드는 더 짧은 비디오 길이와 픽셀 수준의 해상도 제어를 지원합니다.

버전 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": "강에서 뛰는 고양이",
  "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": "강에서 뛰는 고양이",
    "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: '강에서 뛰는 고양이',
    model: 'sora-2',
    seconds: 8,
    size: '1280x720'
  })
});
const data = await response.json();
console.log(data);

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

참조 이미지 사용 (버전 2.0)

버전 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": "아름다운 정원을 걷는 사람",
    "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이어야 합니다.

버전 1.0과 버전 2.0 매개변수 비교

매개변수	버전 1.0	버전 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`	✅ 가로/세로	❌
`size`	✅ 소형/대형	✅ 720x1280/1280x720/1024x1792/1792x1024
`image_urls`	✅ 여러 참조 이미지	✅ 첫 번째 이미지만 사용
`character_url`	✅	❌
`callback_url`	✅	✅

비동기 콜백

Sora 비디오 생성 API의 생성 시간은 상대적으로 길어 약 1-2분이 소요됩니다. API가 오랜 시간 응답하지 않으면 HTTP 요청이 연결을 유지하여 추가 시스템 리소스 소모를 초래하므로, 이 API는 비동기 콜백 지원도 제공합니다. 전체 프로세스는 클라이언트가 요청을 시작할 때 추가로 callback_url 필드를 지정하는 것입니다. 클라이언트가 API 요청을 시작한 후, API는 즉시 결과를 반환하며, 현재 작업 ID를 나타내는 task_id 필드 정보를 포함합니다. 작업이 완료되면 생성된 비디오 결과가 POST JSON 형식으로 클라이언트가 지정한 callback_url로 전송되며, 여기에도 task_id 필드가 포함되어 있어 작업 결과를 ID로 연결할 수 있습니다. 아래 예제를 통해 구체적으로 어떻게 작업하는지 알아보겠습니다. 먼저, Webhook 콜백은 HTTP 요청을 수신할 수 있는 서비스로, 개발자는 자신이 구축한 HTTP 서버의 URL로 교체해야 합니다. 여기서는 편리한 시연을 위해 공개 Webhook 샘플 사이트인 https://webhook.site/를 사용합니다. 해당 사이트를 열면 Webhook URL을 얻을 수 있습니다.

이 URL을 복사하여 Webhook으로 사용할 수 있으며, 여기서의 샘플은 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://platform.cdn.acedata.cloud/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

신원

프록시

고급

Coding

Sora Videos Generation API 연동 설명

신청 절차

기본 사용법(Version 1)

이미지 기반 비디오 작업(Version 1)

캐릭터 생성 비디오 작업 (버전 1)

버전 2.0 모드

버전 2.0 매개변수 설명

기본 예시

참조 이미지 사용 (버전 2.0)

버전 1.0과 버전 2.0 매개변수 비교

비동기 콜백

오류 처리

오류 응답 예시

결론

​신청 절차

​기본 사용법(Version 1)

​이미지 기반 비디오 작업(Version 1)

​캐릭터 생성 비디오 작업 (버전 1)

​버전 2.0 모드

​버전 2.0 매개변수 설명

​기본 예시

​참조 이미지 사용 (버전 2.0)

​버전 1.0과 버전 2.0 매개변수 비교

​비동기 콜백

​오류 처리

​오류 응답 예시

​결론

신청 절차

기본 사용법(Version 1)

이미지 기반 비디오 작업(Version 1)

캐릭터 생성 비디오 작업 (버전 1)

버전 2.0 모드

버전 2.0 매개변수 설명

기본 예시

참조 이미지 사용 (버전 2.0)

버전 1.0과 버전 2.0 매개변수 비교

비동기 콜백

오류 처리

오류 응답 예시

결론