API 레퍼런스
Seedance 텍스트→비디오
텍스트를 비디오로 변환하는 엔드포인트를 사용하여 비동기 Task를 생성하세요.
01
개요
지원되는 모델로 텍스트를 비디오로 변환하는 엔드포인트를 사용하세요. 반환된 Task ID로 상태를 조회하거나, 아래에 문서화된 전달을 위해 callback_url을 제공하세요.
빠른 시작
- API 키를 만들고 RUNAPI_API_KEY로 설정합니다.
- 지원되는 모델을 선택하고 해당 모델의 스키마와 일치하는 본문으로 POST 요청을 전송합니다.
- 반환된 작업 ID를 저장한 후, 터미널 상태가 될 때까지 폴링하거나 아래에 문서화된 콜백을 처리하세요.
엔드포인트
- Base URL
https://runapi.ai- API 버전
v1- 인증
Authorization: Bearer YOUR_API_TOKEN
02
지원 모델
현재 가격, 속도 제한 및 상업적 이용 세부 정보는 모델 페이지를 여십시오.
03
JSON 본문요청 스키마
필드와 허용 값은 선택된 모델에 따라 다릅니다. 제공된 경우 callback_url은 아래에 문서화된 Task 전달을 수신합니다.
seedance-1.5-pro필드 11개
aspect_ratiostring
선택
허용 값:
1:1, 4:3, 3:4, 16:9, 9:16, 21:9
callback_urlstring
선택
duration_secondsinteger
필수
범위:
4 - 12
enable_safety_checkerboolean
선택
generate_audioboolean
선택
lock_cameraboolean
선택
modelstring
선택
output_resolutionstring
선택
허용 값:
480p, 720p, 1080p
promptstring
선택
seedinteger
선택
범위:
-1 - 2147483647
source_image_urlsarray
선택
항목 제한:
2
seedance-2-mini필드 13개
aspect_ratiostring
선택
허용 값:
1:1, 4:3, 3:4, 16:9, 9:16, 21:9, auto
callback_urlstring
선택
duration_secondsinteger
선택
기본값:
5
범위: 4 - 15
first_frame_image_urlstring
선택
generate_audioboolean
선택
last_frame_image_urlstring
선택
modelstring
선택
output_resolutionstring
선택
허용 값:
480p, 720p
promptstring
선택
reference_audio_urlsarray
선택
항목 제한:
3
reference_image_urlsarray
선택
항목 제한:
9
reference_video_urlsarray
선택
항목 제한:
3
web_searchboolean
선택
seedance-2.0필드 14개
aspect_ratiostring
선택
허용 값:
1:1, 4:3, 3:4, 16:9, 9:16, 21:9, auto
callback_urlstring
선택
duration_secondsinteger
선택
기본값:
5
범위: 4 - 15
enable_safety_checkerboolean
선택
first_frame_image_urlstring
선택
generate_audioboolean
선택
last_frame_image_urlstring
선택
modelstring
선택
output_resolutionstring
선택
허용 값:
480p, 720p, 1080p, 4k
promptstring
선택
reference_audio_urlsarray
선택
항목 제한:
3
reference_image_urlsarray
선택
항목 제한:
9
reference_video_urlsarray
선택
항목 제한:
3
web_searchboolean
선택
seedance-2.0-fast필드 14개
aspect_ratiostring
선택
허용 값:
1:1, 4:3, 3:4, 16:9, 9:16, 21:9, auto
callback_urlstring
선택
duration_secondsinteger
선택
기본값:
5
범위: 4 - 15
enable_safety_checkerboolean
선택
first_frame_image_urlstring
선택
generate_audioboolean
선택
last_frame_image_urlstring
선택
modelstring
선택
output_resolutionstring
선택
허용 값:
480p, 720p
promptstring
선택
reference_audio_urlsarray
선택
항목 제한:
3
reference_image_urlsarray
선택
항목 제한:
9
reference_video_urlsarray
선택
항목 제한:
3
web_searchboolean
선택
seedance-2.5필드 16개
aspect_ratiostring
선택
출력 화면 비율; auto로 설정하면 RunAPI가 자동으로 선택합니다.
허용 값:1:1, 4:3, 3:4, 16:9, 9:16, 21:9, auto
기본값: auto
callback_urlstring
선택
비동기 Task 업데이트를 위한 웹훅 URL.
duration_secondsinteger
선택
비디오 길이(초); -1이면 자동으로 길이를 선택합니다.
허용 값:-1, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30
기본값: 5
enable_safety_checkerboolean
선택
RunAPI가 생성된 콘텐츠의 안전성을 검사할지 여부.
first_frame_image_urlstring
선택
프레임 가이드 생성을 위한 공개 첫 번째 프레임 이미지 URL.
generate_audioboolean
선택
동기화된 오디오를 생성할지 여부.
기본값:true
last_frame_image_urlstring
선택
공개 마지막 프레임 이미지 URL. first_frame_image_url이 필요합니다.
modelstring
필수
RunAPI 모델 식별자.
output_formatstring
선택
출력 비디오 컨테이너 형식.
허용 값:mp4, mov
기본값: mp4
output_resolutionstring
선택
출력 비디오 해상도.
허용 값:480p, 720p, 1080p
기본값: 720p
promptstring
필수
비디오 생성 프롬프트.
범위:3 - 30000
reference_audio_urlsarray
선택
공개 참조 오디오 URL. 최대 10개의 오디오 파일.
항목 제한:10
reference_image_urlsarray
선택
공개 참조 이미지 URL. 최대 30개의 이미지.
항목 제한:30
reference_video_urlsarray
선택
공개 참조 비디오 URL. 최대 10개의 비디오.
항목 제한:10
return_last_frameboolean
선택
생성된 비디오의 마지막 프레임을 반환할지 여부.
기본값:false
web_searchboolean
선택
웹 검색으로 프롬프트를 보강할지 여부.
seedance-v1-pro필드 10개
aspect_ratiostring
선택
허용 값:
1:1, 4:3, 3:4, 16:9, 9:16, 21:9
callback_urlstring
선택
duration_secondsinteger
필수
허용 값:
5, 10
enable_safety_checkerboolean
선택
first_frame_image_urlstring
선택
lock_cameraboolean
선택
modelstring
선택
output_resolutionstring
선택
허용 값:
480p, 720p, 1080p
promptstring
선택
seedinteger
선택
seedance-v1-pro-fast필드 8개
callback_urlstring
선택
duration_secondsinteger
필수
허용 값:
5, 10
enable_safety_checkerboolean
선택
first_frame_image_urlstring
필수
modelstring
선택
output_resolutionstring
선택
허용 값:
720p, 1080p
promptstring
선택
seedinteger
선택
범위:
-1 - 2147483647
조건부 규칙
이 요구 사항은 나열된 모든 조건이 일치할 때 적용됩니다.
-
다음의 경우
first_frame_image_url = {"present" => true},model = seedance-2.5- 필수
- 허용되지 않음
reference_image_urls,reference_video_urls,reference_audio_urls
-
다음의 경우
last_frame_image_url = {"present" => true},model = seedance-2.5- 필수
first_frame_image_url- 허용되지 않음
reference_image_urls,reference_video_urls,reference_audio_urls
-
다음의 경우
model = seedance-1.5-pro- 필수
- 허용되지 않음
first_frame_image_url,last_frame_image_url,reference_image_urls,reference_video_urls,reference_audio_urls,web_search,return_last_frame,output_format
-
다음의 경우
model = seedance-2-mini- 필수
- 허용되지 않음
source_image_urls,lock_camera,seed,enable_safety_checker,return_last_frame,output_format
-
다음의 경우
model = seedance-2.0- 필수
- 허용되지 않음
source_image_urls,lock_camera,seed,return_last_frame,output_format
-
다음의 경우
model = seedance-2.0-fast- 필수
- 허용되지 않음
source_image_urls,lock_camera,seed,return_last_frame,output_format
-
다음의 경우
model = seedance-2.5- 필수
- 허용되지 않음
source_image_urls,lock_camera,seed
-
다음의 경우
model = seedance-v1-pro- 필수
- 허용되지 않음
source_image_urls,last_frame_image_url,reference_image_urls,reference_video_urls,reference_audio_urls,web_search,generate_audio,return_last_frame,output_format
-
다음의 경우
model = seedance-v1-pro-fast- 필수
- 허용되지 않음
aspect_ratio,source_image_urls,lock_camera,last_frame_image_url,reference_image_urls,reference_video_urls,reference_audio_urls,web_search,generate_audio,return_last_frame,output_format
04
HTTP 202수락 만들기
POST /api/v1/seedance/text_to_video
응답 스키마
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
},
"task_replayed": {
"type": "boolean"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}응답 예시
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}05
HTTP 200폴링 처리 중
GET /api/v1/seedance/text_to_video/:id
응답 스키마
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}응답 예시
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}06
HTTP 200폴링 완료
GET /api/v1/seedance/text_to_video/:id
응답 스키마
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"last_frame_image_url": {
"type": "string",
"x-runapi-generated-media": true
},
"status": {
"enum": [
"completed"
],
"type": "string"
},
"videos": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
}
},
"required": [
"id",
"status",
"videos",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}응답 예시
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "completed",
"videos": [
{
"url": "https://file.runapi.ai/reference-video.mp4"
}
]
}07
HTTP 200폴링 실패
GET /api/v1/seedance/text_to_video/:id
응답 스키마
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}응답 예시
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": "Task processing failed.",
"id": "tsk_reference_demo",
"status": "failed"
}08
HTTP 200고객 콜백: 완료됨
POST callback_url
응답 스키마
JSON
{
"properties": {
"id": {
"type": "string"
},
"last_frame_image_url": {
"type": "string",
"x-runapi-generated-media": true
},
"status": {
"enum": [
"completed"
],
"type": "string"
},
"videos": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
}
},
"required": [
"id",
"status",
"videos"
],
"type": "object",
"unevaluatedProperties": false
}응답 예시
JSON
{
"id": "tsk_reference_demo",
"status": "completed",
"videos": [
{
"url": "https://file.runapi.ai/reference-video.mp4"
}
]
}09
HTTP 200고객 콜백: 실패함
POST callback_url
응답 스키마
JSON
{
"properties": {
"error": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"code": {
"type": "string"
},
"limit_cents": {
"type": "integer"
},
"message": {
"type": "string"
},
"reset_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"used_cents": {
"type": "integer"
},
"window": {
"enum": [
"1h",
"1d",
"7d",
"daily",
"weekly",
"monthly",
"lifetime"
],
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
]
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error"
],
"type": "object",
"unevaluatedProperties": false
}응답 예시
JSON
{
"error": {
"code": "generation_failed",
"message": "Task processing failed."
},
"id": "tsk_reference_demo",
"status": "failed"
}10
HTTP 401오류
POST /api/v1/seedance/text_to_video
응답 스키마
JSON
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}응답 예시
JSON
{
"error": "Authentication required"
}11
HTTP 401오류
GET /api/v1/seedance/text_to_video/:id
응답 스키마
JSON
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}응답 예시
JSON
{
"error": "Authentication required"
}12
HTTP 400오류
POST /api/v1/seedance/text_to_video
응답 스키마
JSON
{
"oneOf": [
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
},
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 유효성 검사 요약입니다.",
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "공개 요청 필드를 키로 하는 유효성 검사 메시지로, 각 필드에 대해 사람이 읽을 수 있는 문자열 배열이 포함됩니다.",
"type": "object"
}
},
"required": [
"error",
"errors"
],
"type": "object",
"unevaluatedProperties": false
}
]
}응답 예시
JSON
{
"error": "model must be one of: seedance-1.5-pro, seedance-2-mini, seedance-2.0, seedance-2.0-fast, seedance-2.5, seedance-v1-pro, seedance-v1-pro-fast"
}13
HTTP 402오류
POST /api/v1/seedance/text_to_video
응답 스키마
JSON
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}응답 예시
JSON
{
"error": "Insufficient balance"
}14
HTTP 429오류
POST /api/v1/seedance/text_to_video
응답 스키마
JSON
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}응답 예시
JSON
{
"error": "API key credit limit exceeded"
}15
HTTP 409오류
POST /api/v1/seedance/text_to_video
응답 스키마
JSON
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}응답 예시
JSON
{
"error": "The request uses features that are not supported for the selected model"
}16
HTTP 429오류
POST /api/v1/seedance/text_to_video
응답 스키마
JSON
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}응답 예시
JSON
{
"error": "Rate limit reached. Please retry later."
}17
HTTP 503오류
POST /api/v1/seedance/text_to_video
응답 스키마
JSON
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}응답 예시
JSON
{
"error": "Service under maintenance, please try again later"
}18
HTTP 504오류
POST /api/v1/seedance/text_to_video
응답 스키마
JSON
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}응답 예시
JSON
{
"error": "The request timed out"
}19
HTTP 404오류
GET /api/v1/seedance/text_to_video/:id
응답 스키마
JSON
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}응답 예시
JSON
{
"error": "Task with id 'tsk_reference_demo' not found"
}20
생성된 코드 샘플
cURL을 직접 사용하거나 해당 언어의 SDK를 설치하세요. 각 샘플은 이 레퍼런스에 표시된 유효성 검사된 요청을 제출합니다.
설치
Shell
pip install runapi-seedance
PYTHON
import os
from runapi.seedance import SeedanceClient
client = SeedanceClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.text_to_video.create(
model="seedance-1.5-pro",
duration_seconds=5,
prompt="A time-lapse of clouds moving over a mountain lake."
)