메인 콘텐츠로 건너뛰기
POST
/
v1
/
videos
/
generations
curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "veo3.1-fast-official",
    "prompt": "a golden retriever running on the beach, sunset, cinematic",
    "duration": 8,
    "aspect_ratio": "16:9"
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_xxxxxxxxxx"
    }
  ]
}

curl --request POST \
  --url https://api.apimart.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "veo3.1-fast-official",
    "prompt": "a golden retriever running on the beach, sunset, cinematic",
    "duration": 8,
    "aspect_ratio": "16:9"
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_xxxxxxxxxx"
    }
  ]
}

​
인증

​
Authorization
string
필수
모든 API 엔드포인트에서 Bearer Token 인증이 필요합니다API Key 획득:API Key 관리 페이지에 접속하여 API Key를 획득하세요사용 시 요청 헤더에 추가:
Authorization: Bearer YOUR_API_KEY

​
요청 파라미터

​
model
string
필수
비디오 생성 모델명사용 가능한 모델:
  • veo3.1-fast-official - Veo 3.1 공식 빠른 버전
  • veo3.1-quality-official - Veo 3.1 공식 고품질 버전
​
prompt
string
필수
긍정 텍스트 프롬프트장면, 동작, 스타일 등을 자세히 설명하면 더 좋은 생성 결과를 얻을 수 있습니다. 영어 프롬프트 사용을 권장합니다.예시: "a golden retriever running on the beach, sunset, cinematic"
​
negative_prompt
string
원하지 않는 콘텐츠를 제외하기 위한 부정 프롬프트예시: "blurry, low quality, watermark, text"
​
duration
integer
기본값:"8"
비디오 길이(초)권장값: 4 / 6 / 8기본값: 8⚠️ 주의: 순수 숫자(예: 8)를 입력해야 합니다. 따옴표를 추가하면 오류가 발생합니다
​
aspect_ratio
string
기본값:"16:9"
비디오 화면 비율선택 가능한 값:
  • 16:9 - 가로
  • 9:16 - 세로
기본값: 16:9
​
resolution
string
기본값:"720p"
비디오 해상도선택 가능한 값:
  • 720p - 표준 해상도
  • 1080p - 고화질
  • 4K - 초고화질
기본값: 720p
​
first_frame_image
string
첫 프레임 이미지 URL, 이미지-투-비디오 생성에 사용
  • 이미지 URL은 공개 접근 가능하고 핫링크 보호가 없어야 합니다
  • 임시 다운로드 링크 대신 오브젝트 스토리지 URL 사용을 권장합니다
​
last_frame_image
string
끝 프레임 이미지 URL, 이미지-투-비디오 생성에 사용first_frame_image와 함께 사용하여 첫·끝 프레임 제어를 구현합니다
​
seed
integer
생성 결과를 재현하기 위한 랜덤 시드값 범위: 0 - 4294967295
​
sample_count
integer
기본값:"1"
생성 샘플 수 1-4, 현재 1 사용을 권장기본값: 1
​
generate_audio
boolean
기본값:"false"
오디오 트랙 생성 여부
​
person_generation
string
기본값:"allow_adult"
인물 생성 정책선택 가능한 값:
  • allow_adult - 성인 인물/얼굴 생성만 허용
  • disallow - 인물 또는 얼굴 생성을 허용하지 않음
기본값: allow_adult
​
resize_mode
string
기본값:"pad"
이미지 리사이즈 전략(이미지-투-비디오 시 적용)선택 가능한 값:
  • pad - 패딩 모드
  • crop - 크롭 모드
기본값: pad
​
enhance_prompt
boolean
기본값:"true"
업스트림 프롬프트 강화 활성화 여부기본값: true
  • 이 매개변수는 true로만 설정할 수 있습니다. false로 설정하면 요청 오류가 발생합니다
  • 이 매개변수가 필요하지 않은 경우 전송하지 마세요

​
텍스트-투-비디오 vs 이미지-투-비디오

시스템은 이미지 매개변수 전달 여부로 자동으로 모드를 판단합니다: 이미지 없으면 텍스트-투-비디오, 이미지 있으면 이미지-투-비디오.
매개변수텍스트-투-비디오이미지-투-비디오
prompt✅ 필수✅ 필수
first_frame_image❌ 불필요✅ 최소 하나 필요
last_frame_image❌ 불필요✅ 선택 사항(끝 프레임)
negative_prompt✅ 선택 사항✅ 선택 사항
duration✅ 선택 사항✅ 선택 사항
aspect_ratio✅ 선택 사항✅ 선택 사항
resolution✅ 선택 사항✅ 선택 사항
seed✅ 선택 사항✅ 선택 사항
generate_audio✅ 선택 사항✅ 선택 사항
person_generation✅ 선택 사항✅ 선택 사항
resize_mode❌ 해당 없음✅ 선택 사항
enhance_prompt✅ 선택 사항✅ 선택 사항

​
응답

​
code
integer
응답 상태 코드, 성공 시 200
​
data
array
응답 데이터 배열

​
사용 시나리오

​
시나리오 1: 텍스트-투-비디오(기본)

{
  "model": "veo3.1-fast-official",
  "prompt": "a golden retriever running on the beach, sunset, cinematic"
}

​
시나리오 2: 텍스트-투-비디오(전체 매개변수)

{
  "model": "veo3.1-quality-official",
  "prompt": "a cinematic close-up of a ragdoll cat slowly walking through a sunlit living room",
  "negative_prompt": "blurry, low quality, watermark, text",
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "1080p",
  "seed": 12345,
  "generate_audio": true,
  "person_generation": "disallow",
  "enhance_prompt": true
}

​
시나리오 3: 이미지-투-비디오(첫 프레임 1장)

{
  "model": "veo3.1-fast-official",
  "prompt": "the cat slowly walks forward and looks around",
  "first_frame_image": "https://example.com/cat.png",
  "duration": 8,
  "resolution": "720p"
}

​
시나리오 4: 이미지-투-비디오(첫 프레임 + 끝 프레임)

{
  "model": "veo3.1-quality-official",
  "prompt": "smooth cinematic transition from the first frame to the last frame",
  "first_frame_image": "https://example.com/frame-start.png",
  "last_frame_image": "https://example.com/frame-end.png",
  "duration": 8,
  "resolution": "1080p"
}

​
시나리오 5: 오디오 포함 비디오 생성

{
  "model": "veo3.1-quality-official",
  "prompt": "a busy coffee shop with people chatting and barista making latte art",
  "duration": 8,
  "generate_audio": true,
  "aspect_ratio": "16:9"
}
작업 결과 조회비디오 생성은 비동기 작업으로, 제출 후 task_id가 반환됩니다. 작업 상태 조회 엔드포인트를 사용하여 생성 진행 상황과 결과를 조회하세요.