Video 생성 AI API

kvidAI의 Video 생성 AI API는 텍스트나 이미지를 입력으로 받아 5-6초 길이의 고품질 비디오를 생성하는 서비스입니다.

🎯 서비스 개요

지원 기능

Text-to-Video: 텍스트 프롬프트로 비디오 생성
Image-to-Video: 이미지를 기반으로 한 비디오 생성
v1 모델: 480p, 580p, 720p 지원 (5-6초)
v2 모델: 480p, 720p, 1080p 지원 (5초 또는 10초)

특화 기능

카메라 앵글 조작 프롬프트 지원 (완벽하지 않을 수 있음)
다양한 생성 옵션 및 제어 가능

📡 API 엔드포인트

기본 정보

Base URL: https://api.kvid.ai
api-key: api_key Header
Content-Type: application/json

API 엔드포인트

Text-to-Video

생성: POST https://api.kvid.ai/ai/video/text-to-video/generate
상태 확인: GET https://api.kvid.ai/ai/video/text-to-video/status?request_id={request_id}
결과 가져오기: GET https://api.kvid.ai/ai/video/text-to-video/result?request_id={request_id}

Image-to-Video

생성: POST https://api.kvid.ai/ai/video/image-to-video/generate
상태 확인: GET https://api.kvid.ai/ai/video/image-to-video/status?request_id={request_id}
결과 가져오기: GET https://api.kvid.ai/ai/video/image-to-video/result?request_id={request_id}

1. Text-to-Video 생성

v1 모델 요청 예제

import requests
import json

url = "https://api.kvid.ai/ai/video/text-to-video/generate"
api_key = "YOUR_API_KEY"

# v1 모델 (wan-t2v)
payload = json.dumps({
    "prompt": "A waterfall flowing down a mountain, nature documentary style",
    "negative_prompt": "low quality, bad anatomy",
    "num_frames": 81,
    "frames_per_second": 16,
    "seed": None,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "num_inference_steps": 30,
    "enable_safety_checker": True,
    "enable_prompt_expansion": True
})

headers = {
    'api-key': api_key,
    'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)
result = response.json()
request_id = result['data']['request_id']
print(f"Request ID: {request_id}")

v2 모델 요청 예제

# v2 모델 (bytedance/seedance)
payload = json.dumps({
    "prompt": "A beautiful sunset over the ocean",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": "5",
    "camera_fixed": False,
    "seed": None,
    "model": "bytedance/seedance/v1/lite/text-to-video"
})

response = requests.request("POST", url, headers=headers, data=payload)

2. Image-to-Video 생성

v1 모델 요청 예제

import requests
import json

url = "https://api.kvid.ai/ai/video/image-to-video/generate"
api_key = "YOUR_API_KEY"

# v1 모델 (wan-i2v)
payload = json.dumps({
    "prompt": "Make the subject move naturally",
    "negative_prompt": "low quality, bad anatomy",
    "num_frames": 81,
    "frames_per_second": 16,
    "seed": None,
    "resolution": "720p",
    "aspect_ratio": "auto",
    "num_inference_steps": 30,
    "enable_safety_checker": True,
    "enable_prompt_expansion": True,
    "image_url": "https://your-image-url.jpg"
})

headers = {
    'api-key': api_key,
    'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)
result = response.json()
request_id = result['data']['request_id']
print(f"Request ID: {request_id}")

v2 모델 요청 예제

# v2 모델 (bytedance/seedance)
payload = json.dumps({
    "prompt": "Camera panning across the scene",
    "resolution": "1080p",
    "duration": "5",
    "camera_fixed": False,
    "seed": None,
    "model": "bytedance/seedance/v1/lite/image-to-video",
    "image_url": "https://your-image-url.jpg"
})

response = requests.request("POST", url, headers=headers, data=payload)

3. 생성 상태 조회

상태 확인 예제

import requests
import time

api_key = "YOUR_API_KEY"
request_id = "req_12345abcdef"  # 생성 요청에서 받은 request_id

# Text-to-Video 상태 확인
url = f"https://api.kvid.ai/ai/video/text-to-video/status?request_id={request_id}"

headers = {
    'api-key': api_key
}

# 상태 폴링
while True:
    response = requests.get(url, headers=headers)
    result = response.json()
    
    status = result['data']['status']
    progress = result['data']['progress']
    
    print(f"Status: {status}, Progress: {progress}%")
    
    if status == 'COMPLETED':
        print("비디오 생성 완료!")
        break
    elif status == 'FAILED':
        print("비디오 생성 실패")
        break
    
    time.sleep(5)  # 5초 대기

4. 비디오 결과 가져오기

결과 조회 예제

import requests

api_key = "YOUR_API_KEY"
request_id = "req_12345abcdef"

# Text-to-Video 결과 조회
url = f"https://api.kvid.ai/ai/video/text-to-video/result?request_id={request_id}"

headers = {
    'api-key': api_key
}

response = requests.get(url, headers=headers)
result = response.json()

if result['success']:
    video_url = result['data']['url']
    video_name = result['data']['name']
    video_size = result['data']['size']
    
    print(f"비디오 URL: {video_url}")
    print(f"파일명: {video_name}")
    print(f"파일 크기: {video_size} KB")
else:
    print(f"오류: {result['message']}")

📋 매개변수 상세

Text-to-Video 매개변수

v1 모델

매개변수	타입	기본값	설명
`prompt`	string	필수	비디오 생성을 위한 텍스트 프롬프트
`negative_prompt`	string	""	제외할 요소 설명
`num_frames`	integer	81	프레임 수 (81-100)
`frames_per_second`	integer	16	초당 프레임 수 (5-24)
`seed`	integer/null	null	재현성을 위한 시드값
`resolution`	string	"720p"	해상도 ("480p", "580p", "720p")
`aspect_ratio`	string	"16:9"	화면 비율 ("16:9", "9:16")
`num_inference_steps`	integer	30	추론 단계 수
`enable_safety_checker`	boolean	true	안전 필터 활성화
`enable_prompt_expansion`	boolean	true	프롬프트 확장 활성화

v2 모델

매개변수	타입	기본값	설명
`prompt`	string	필수	비디오 생성을 위한 텍스트 프롬프트
`aspect_ratio`	string	"16:9"	화면 비율 ("16:9", "4:3", "1:1", "9:21")
`resolution`	string	"720p"	해상도 ("480p", "720p", "1080p")
`duration`	string	"5"	비디오 길이 ("5", "10")
`camera_fixed`	boolean	false	카메라 고정 여부
`seed`	integer/null	null	재현성을 위한 시드값
`model`	string	필수	"bytedance/seedance/v1/lite/text-to-video"

Image-to-Video 매개변수

v1 모델

Text-to-Video v1과 동일한 매개변수에 추가로:

매개변수	타입	기본값	설명
`image_url`	string	필수	입력 이미지 URL
`image_file`	string	-	Base64 인코딩된 이미지 데이터
`aspect_ratio`	string	"auto"	화면 비율 ("auto", "16:9", "9:16", "1:1")

v2 모델

Text-to-Video v2와 동일한 매개변수에 추가로:

매개변수	타입	기본값	설명
`image_url`	string	필수	입력 이미지 URL
`image_file`	string	-	Base64 인코딩된 이미지 데이터
`end_image_url`	string/null	null	종료 이미지 URL (선택)

API 응답 형식

Generate 응답

{
  "success": true,
  "data": {
    "request_id": "req_12345abcdef"
  },
  "message": "Video generation request submitted successfully"
}

Status 응답

{
  "success": true,
  "data": {
    "status": "PROCESSING",
    "progress": 45,
    "logs": [
      "2024-01-15 10:30:00 - Video generation started",
      "2024-01-15 10:30:15 - Processing frame 1-20"
    ]
  },
  "message": "Video generation in progress"
}

Result 응답

{
  "success": true,
  "data": {
    "url": "https://storage.kvid.ai/videos/req_12345abcdef.mp4",
    "name": "generated_video.mp4",
    "size": 15420
  },
  "message": "Video result retrieved successfully"
}

오류 응답 스키마

기본 오류 응답 형식

{
  "success": false,
  "data": {
    "success": false,
    "error": "ValidationError",
    "message": "오류 메시지",
    "details": {
      "error_type": "오류_타입",
      "error_message": "상세 오류 메시지",
      "location": ["body", "parameter_name"],
      "validation_context": {},
      "help_url": "https://docs.fal.ai/errors#error_type",
      "input_value": "입력값",
      "http_status": 422,
      "full_details": []
    }
  }
}

주요 오류 타입

오류 타입	설명	HTTP 상태	해결 방법
`RESULT_FETCH_ERROR`	결과를 가져오는데 실패	400	요청이 아직 진행 중이거나 오류가 발생했습니다. 상태를 확인해주세요
`PROMPT_VALIDATION_ERROR`	프롬프트 검증 실패	400	프롬프트에 허용되지 않는 문자가 포함되어 있습니다. 영어와 기본 특수문자만 사용해주세요
`NEGATIVE_PROMPT_VALIDATION_ERROR`	네거티브 프롬프트 검증 실패	400	네거티브 프롬프트에 허용되지 않는 문자가 포함되어 있습니다. 영어와 기본 특수문자만 사용해주세요
`USER_NOT_FOUND`	사용자를 찾을 수 없음	404	등록된 이메일인지 확인해주세요
`CONFIGURATION_ERROR`	서버 설정 오류	500	서버 설정을 확인해주세요. 관리자에게 문의하세요
`ValidationError`	입력값 검증 실패	422	요청 파라미터를 확인하고 수정해주세요
`internal_server_error`	내부 서버 오류	500	잠시 후 다시 시도해주세요
`generation_timeout`	생성 시간 초과	504	더 간단한 프롬프트나 낮은 해상도로 시도해보세요
`content_policy_violation`	콘텐츠 정책 위반	422	프롬프트가 안전 정책을 위반했습니다. 내용을 수정해주세요
`downstream_service_error`	외부 서비스 오류	503	AI 모델 서비스에 문제가 있습니다. 잠시 후 시도해주세요
`downstream_service_unavailable`	외부 서비스 사용 불가	503	AI 모델 서비스가 일시적으로 사용할 수 없습니다

검증 오류 세부 타입

error_type	설명	validation_context 예시
`image_too_small`	이미지가 너무 작음	`{"min_height": 300, "min_width": 300}`
`image_too_large`	이미지가 너무 큼	`{"max_height": 6000, "max_width": 6000}`
`image_load_error`	이미지 로드 실패	`{"url": "invalid_url"}`
`file_download_error`	파일 다운로드 실패	`{"url": "unreachable_url"}`
`greater_than`	최소값보다 작음	`{"limit_value": 0}`
`less_than`	최대값보다 큼	`{"limit_value": 100}`
`sequence_too_short`	시퀀스가 너무 짧음	`{"min_length": 1}`
`sequence_too_long`	시퀀스가 너무 김	`{"max_length": 4}`
`one_of`	허용되지 않은 값	`{"allowed_values": ["480p", "720p", "1080p"]}`

오류 응답 예시

이미지 크기 검증 오류:

{
  "success": false,
  "data": {
    "success": false,
    "error": "ValidationError",
    "message": "Image dimensions are too small. Minimum dimensions required: 300x300 pixels.",
    "details": {
      "error_type": "image_too_small",
      "error_message": "Image dimensions are too small. Minimum dimensions required: 300x300 pixels.",
      "location": ["body", "image_url"],
      "validation_context": {
        "min_height": 300,
        "min_width": 300
      },
      "help_url": "https://docs.fal.ai/errors#image_too_small",
      "input_value": "https://example.com/small-image.png",
      "http_status": 422,
      "full_details": [
        {
          "loc": ["body", "image_url"],
          "msg": "Image dimensions are too small. Minimum dimensions required: 300x300 pixels.",
          "type": "image_too_small",
          "url": "https://docs.fal.ai/errors#image_too_small",
          "ctx": {
            "min_height": 300,
            "min_width": 300
          },
          "input": "https://example.com/small-image.png"
        }
      ]
    }
  }
}

해상도 값 검증 오류:

{
  "success": false,
  "data": {
    "success": false,
    "error": "ValidationError",
    "message": "Input should be '480p', '720p' or '1080p'",
    "details": {
      "error_type": "one_of",
      "error_message": "Input should be '480p', '720p' or '1080p'",
      "location": ["body", "resolution"],
      "validation_context": {
        "allowed_values": ["480p", "720p", "1080p"]
      },
      "help_url": "https://docs.kvid.ai//docs/ko/api-services/video-api",
      "input_value": "4K",
      "http_status": 422
    }
  }
}

결과 조회 오류:

{
  "success": false,
  "data": {
    "success": false,
    "error": "RESULT_FETCH_ERROR",
    "message": "결과를 가져오는데 실패했습니다.",
    "details": {
      "error_type": "RESULT_FETCH_ERROR",
      "error_message": "요청이 아직 진행 중이거나 오류가 발생했습니다. 상태를 확인해주세요.",
      "location": ["query", "request_id"],
      "validation_context": {},
      "help_url": "https://docs.kvid.ai/errors#result_fetch_error",
      "input_value": "req_invalid_id",
      "http_status": 400,
      "full_details": []
    }
  }
}

프롬프트 검증 오류:

{
  "success": false,
  "error": "PROMPT_VALIDATION_ERROR",
  "message": "프롬프트에 허용되지 않는 문자가 포함되어 있습니다.",
  "details": {
    "help_url": "https://docs.kvid.ai/docs/ko/api-services/video-api",
    "http_status": 400,
    "error_message": "프롬프트에 허용되지 않는 문자가 포함되어 있습니다. 영어와 기본 특수문자만 사용해주세요."
  }
}

사용자 인증 오류:

{
  "success": false,
  "error": "USER_NOT_FOUND",
  "message": "사용자를 찾을 수 없습니다.",
  "details": {
    "help_url": "https://docs.kvid.ai/docs/ko/api-services/video-api",
    "http_status": 404,
    "error_message": "등록된 이메일인지 확인해주세요."
  }
}

서버 설정 오류:

{
  "success": false,
  "error": "CONFIGURATION_ERROR",
  "message": "FAL_KEY 환경변수가 설정되지 않았습니다.",
  "details": {
    "help_url": "https://docs.kvid.ai/docs/ko/api-services/video-api",
    "http_status": 500,
    "error_message": "서버 설정을 확인해주세요."
  }
}

🎬 사용 예제

1. 등산객과 배낭 비디오

등산객 배낭

프롬프트: A video of a man hiking with a backpack. The bag must be the main subject. Walking slowly

2. 청소기 사용 비디오

진공청소기

프롬프트: Video of cleaning with a vacuum cleaner. slow movement. low angle

3. 음식 홍보 비디오

연어 요리

프롬프트: Remove the cooking effect and only add camera movement. highlight the food in Zoom format. promotional video for this food

4. 한국 전통 정자 비디오

전주 공원

프롬프트: A traditional Korean pavilion by a lotus pond, with two small dogs (a white poodle and a brown shiba inu) joyfully running along the wooden walkway. The pond is filled with green lotus leaves, and the background is full of lush green trees. Bright sunny day, peaceful and vivid atmosphere.

Text-to-Video 버전:

추가 프롬프트: The two small dogs (white poodle and brown shiba inu) approach the pavilion, wagging their tails, playfully interacting. They stop at the end of the deck, looking around curiously. [Over-the-shoulder shot] Captures the view of the park and lotus pond from behind the dogs.

5. 호랑이 이미지-비디오 변환

호랑이

프롬프트: The tiger briefly pulls back its tongue, blinks, and tilts its head slightly. Then immediately sticks out its tongue for a second time, a bit longer than the first, while lowering its head slightly. [Low-angle close-up shot] Capture from below to show both majesty and cuteness.

⚠️ 제한사항 및 주의사항

기술적 제한

v1 모델: 5-6초 고정, 최대 720p
v2 모델: 5초 또는 10초, 최대 1080p
카메라 앵글: 카메라 앵글 조작 프롬프트가 항상 정확하게 작동하지 않을 수 있음
처리 시간: 해상도와 길이에 따라 1-5분 소요
이미지 입력 제한: 동영상 생성을 위한 기반 이미지의 크기는 300300 - 60006000 사이 제한

최적화 팁

구체적인 프롬프트: 세부적이고 명확한 설명 제공
카메라 앵글: 필요시 [Low-angle], [Over-the-shoulder shot] 등의 지시어 사용
적절한 해상도: 용도에 맞는 해상도 선택

🔗 관련 링크

💰 요금 정보

Video Generation API의 자세한 요금 정보는 요금제 페이지를 참고해 주세요.

📞 지원 및 문의

문의사항이 있으시면 다음 경로로 연락해 주세요:

이메일: [email protected]
디스코드: kvidAI 커뮤니티

🎯 서비스 개요​

지원 기능​

특화 기능​

📡 API 엔드포인트​

기본 정보​

API 엔드포인트​

Text-to-Video​

Image-to-Video​

1. Text-to-Video 생성​

2. Image-to-Video 생성​

3. 생성 상태 조회​

4. 비디오 결과 가져오기​

📋 매개변수 상세​

Text-to-Video 매개변수​

v1 모델​

v2 모델​

Image-to-Video 매개변수​

v1 모델​

v2 모델​

API 응답 형식​

Generate 응답​

Status 응답​

Result 응답​

오류 응답 스키마​

기본 오류 응답 형식​

주요 오류 타입​

검증 오류 세부 타입​

오류 응답 예시​

🎬 사용 예제​

1. 등산객과 배낭 비디오​

2. 청소기 사용 비디오​

3. 음식 홍보 비디오​

4. 한국 전통 정자 비디오​

5. 호랑이 이미지-비디오 변환​

⚠️ 제한사항 및 주의사항​

기술적 제한​

최적화 팁​

🔗 관련 링크​

💰 요금 정보​

📞 지원 및 문의​

🎯 서비스 개요

지원 기능

특화 기능

📡 API 엔드포인트

기본 정보

API 엔드포인트

Text-to-Video

Image-to-Video

1. Text-to-Video 생성

2. Image-to-Video 생성

3. 생성 상태 조회

4. 비디오 결과 가져오기

📋 매개변수 상세

Text-to-Video 매개변수

v1 모델

v2 모델

Image-to-Video 매개변수

v1 모델

v2 모델

API 응답 형식

Generate 응답

Status 응답

Result 응답

오류 응답 스키마

기본 오류 응답 형식

주요 오류 타입

검증 오류 세부 타입

오류 응답 예시

🎬 사용 예제

1. 등산객과 배낭 비디오

2. 청소기 사용 비디오

3. 음식 홍보 비디오

4. 한국 전통 정자 비디오

5. 호랑이 이미지-비디오 변환

⚠️ 제한사항 및 주의사항

기술적 제한

최적화 팁

🔗 관련 링크

💰 요금 정보

📞 지원 및 문의