이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Vertex AI의 Veo 동영상 생성 API

Veo는 동영상 생성을 지원하는 모델의 이름입니다. Veo는 사용자가 제공한 텍스트 프롬프트 또는 이미지 프롬프트에서 동영상을 생성합니다. Veo에 대한 자세한 내용은 Veo 동영상 생성 개요를 참조하세요.

콘솔에서 이 모델을 살펴보려면 Model Garden의 Video Generation 모델 카드를 참조하세요.

Vertex AI(Vertex AI Studio)에서 Veo 사용해 보기

Colab에서 Veo 사용해 보기

지원되는 모델

Veo API는 다음 모델을 지원합니다.

자세한 내용은 Veo 모델을 참조하세요.

HTTP 요청

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:predictLongRunning \

-d '{
  "instances": [
    {
      "prompt": string,
      "image": {
        // Union field can be only one of the following:
        "bytesBase64Encoded": string,
        "gcsUri": string,
        // End of list of possible types for union field.
        "mimeType": string
      },
      "lastFrame": {
        // Union field can be only one of the following:
        "bytesBase64Encoded": string,
        "gcsUri": string,
        // End of list of possible types for union field.
        "mimeType": string
      },
      "video": {
        // Union field can be only one of the following:
        "bytesBase64Encoded": string,
        "gcsUri": string,
        // End of list of possible types for union field.
        "mimeType": string
      },
      "mask": {
        // Union field can be only one of the following:
        "bytesBase64Encoded": string,
        "gcsUri": string,
        // End of list of possible types for union field.
        "mimeType": string,
        "maskMode": string
      },
      "referenceImages": [
        // A list of up to three asset images or at most one style image for the
        // model to use when generating videos.
        //
        // referenceImages is supported by the following models in Preview:
        //
        // *   veo-2.0-generate-exp
        // *   veo-3.1-generate-preview
        {
        "image:" {
          // Union field can be only one of the following:
          "bytesBase64Encoded": string,
          "gcsUri": string,
          // End of list of possible types for union field.
          "mimeType": string
        },
        "referenceType": string
        }
      ]
    }
  ],
  "parameters": {
    "aspectRatio": string,
    "compressionQuality": string,
    "durationSeconds": integer,
    "enhancePrompt": boolean,
    "generateAudio": boolean,
    "negativePrompt": string,
    "personGeneration": string,
    "resizeMode": string, // Veo 3 image-to-video only
    "resolution": string, // Veo 3 models only
    "sampleCount": integer,
    "seed": uint32,
    "storageUri": string
  }
}'

인스턴스

인스턴스
`prompt`	`string` 텍스트를 동영상으로 변환하는 데 필요합니다. 입력 이미지 프롬프트가 제공된 경우 선택사항(이미지 동영상 변환) 동영상의 처음 8초를 안내하는 텍스트 문자열입니다. 예를 들면 다음과 같습니다. 렌즈 플레어, 입체 광원이 적용된 밝은 네온사인, 날아다니는 자동차, 안개가 있는 밤의 번화한 디스토피아 도시를 빠르게 지나가는 장면 빠른 속도로 달리는 자동차의 네온 홀로그램, 빛의 속도, 영화 스타일, 놀라운 디테일, 입체 광원 물속에서 박동하듯이 움직이는 여러 개의 점박이 해파리. 심해에서 빛나는 투명한 몸 밝은 네온사인이 있는 분주한 미래지향적인 도쿄 도시의 밤 거리가 비치는 물웅덩이를 극단적으로 클로즈업하고 얕은 피사계 심도와 렌즈 플레어를 적용해 줘 북극 하늘을 가로지르는 오로라의 타임랩스, 별이 반짝이는 눈 덮인 풍경 아름다운 일몰을 배경으로 혼자 말을 타고 대초원을 가로지르는 카우보이를 부드러운 빛과 따뜻한 색조로 표현해 줘
`image`	통합 필드 선택사항입니다. 동영상 생성을 안내하는 이미지입니다. 이미지를 인코딩하는 `bytesBase64Encoded` 문자열 또는 Cloud Storage 버킷 위치에 대한 `gcsUri` 문자열 URI일 수 있습니다.
`lastFrame`	통합 필드 선택사항입니다. 동영상의 첫 번째 프레임 이미지로, 공간 사이를 채웁니다. `lastFrame`은 이미지를 인코딩하는 `bytesBase64Encoded` 문자열이거나 Cloud Storage 버킷 위치에 대한 `gcsUri` 문자열 URI일 수 있습니다. `lastFrame`는 미리보기에서 다음 모델로 지원됩니다. `veo-2.0-generate-001` `veo-3.0-generate-exp` `veo-3.1-generate-preview` `veo-3.1-fast-generate-preview`
`video`	통합 필드 선택사항입니다. 길이를 늘릴 Veo 생성 동영상입니다. 동영상을 인코딩하는 `bytesBase64Encoded` 문자열 또는 Cloud Storage 버킷 위치에 대한 `gcsUri` 문자열 URI일 수 있습니다. `video`는 미리보기에서 다음 모델로 지원됩니다. `veo-2.0-generate-001` `veo-3.0-generate-exp`
`mask`	통합 필드 (선택사항) 동영상에 적용하여 동영상에서 객체를 추가하거나 삭제하는 마스크 이미지입니다. `mask`은 이미지를 인코딩하는 `bytesBase64Encoded` 문자열이거나 Cloud Storage 버킷 위치에 대한 `gcsUri` 문자열 URI일 수 있습니다. `mask`는 미리보기에서 `veo-2.0-generate-preview`로 지원됩니다.
`referenceImages`	`list[referenceImages]` (선택사항) 동영상을 생성할 때 모델이 사용할 `referenceImages`를 설명하는 최대 3개의 애셋 이미지 또는 최대 1개의 스타일 이미지 목록입니다. 중요: Veo 3.1 모델은 `referenceImages.style`를 지원하지 않습니다. 스타일 이미지를 사용하는 경우 `veo-2.0-generate-exp`를 사용합니다. `referenceImages`는 미리보기에서 다음 모델로 지원됩니다. `veo-2.0-generate-exp` `veo-3.1-generate-preview`
`referenceImages.image`	통합 필드 선택사항입니다. `veo-2.0-generate-exp`의 참고 이미지를 포함하여 주제 입력으로 사용합니다. 각 이미지는 이미지를 인코딩하는 `bytesBase64Encoded` 문자열이거나 Cloud Storage 버킷 위치에 대한 `gcsUri` 문자열 URI일 수 있습니다.
`referenceImages.referenceType`	`string` `referenceImages` 객체에 필요합니다. 제공된 참고 이미지의 유형을 지정합니다. 다음과 같은 값이 지원됩니다. `"asset"`: 참고 이미지는 생성된 동영상의 애셋(예: 장면, 객체, 캐릭터)을 제공합니다. `"style"`: 참고 이미지는 생성된 동영상의 스타일 정보(예: 장면 색상, 조명, 텍스처)를 제공합니다. 중요: Veo 3.1 모델은 `referenceImages.style`를 지원하지 않습니다. 스타일 이미지를 사용하는 경우 `veo-2.0-generate-exp`를 사용합니다.
`bytesBase64Encoded`	`string` 이미지 또는 동영상 파일을 base64로 인코딩한 바이트 문자열입니다. 다음 객체와 함께 사용됩니다. `image` `video` `lastFrame` `referenceImages.image`
`gcsUri`	`string` Cloud Storage 버킷 위치의 문자열 URI입니다. 다음 객체와 함께 사용됩니다. `image` `video` `lastFrame` `referenceImages.image`
`mimeType`	`string` 다음 객체에 필요합니다. `image` `video` `mask` `lastFrame` `referenceImages.image` 동영상 또는 이미지의 MIME 유형을 지정합니다. 이미지의 경우 다음 MIME 유형이 허용됩니다. `image/jpeg` `image/png` `image/webp` 동영상의 경우 다음 MIME 유형이 허용됩니다. `video/mov` `video/mpeg` `video/mp4` `video/mpg` `video/avi` `video/wmv` `video/mpegps` `video/flv`

파라미터

파라미터
`aspectRatio`	`string` 선택사항입니다. 생성된 동영상의 가로세로 비율을 지정합니다. 허용되는 값은 다음과 같습니다. `"16:9"` `"9:16"` 기본값은 `"16:9"`입니다.
`compressionQuality`	`string` 선택사항입니다. 생성된 동영상의 압축 품질을 지정합니다. 허용되는 값은 `"optimized"` 또는 `"lossless"`입니다. 기본값은 `"optimized"`입니다.
`durationSeconds`	`integer` 필수 항목입니다. 생성하려는 동영상 파일의 길이(초)입니다. 허용되는 값은 다음과 같습니다. Veo 2 모델: `5`~`8`. 기본값은 `8`입니다. Veo 3 모델: `4`, `6` 또는 `8`. 기본값은 `8`입니다. `referenceImages`를 사용하는 경우: `8` 자세한 내용은 Veo 모델을 참조하세요.
`enhancePrompt`	`boolean` 선택사항입니다. Gemini를 사용하여 프롬프트를 개선합니다. 허용되는 값은 `true` 또는 `false`입니다. 기본값은 `true`입니다.
`generateAudio`	`boolean` Veo 3 모델에 필요합니다. 동영상의 오디오를 생성합니다. 허용되는 값은 `true` 또는 `false`입니다. `generateAudio`는 `veo-2.0-generate-001` 또는 `veo-2.0-generate-exp`에서 지원되지 않습니다. 사용 가능한 Veo 모델에 대한 자세한 내용은 Veo 모델을 참조하세요.
`negativePrompt`	`string` 선택사항입니다. 모델에서 생성하지 않게 하려는 항목을 설명하는 텍스트 문자열입니다. 예를 들면 다음과 같습니다. 머리 위에서 비치는 조명, 밝은 색상 사람, 동물 여러 대의 자동차, 바람
`personGeneration`	`string` 선택사항입니다. 사람 또는 얼굴 생성 허용 여부를 제어하는 안전 설정입니다. 다음 중 하나입니다. `"allow_adult"`(기본값): 성인만 생성합니다. `"dont_allow"`: 이미지에 사람이나 얼굴을 포함하지 않습니다.
`resizeMode`	`string` (선택사항) Veo 3 모델에만 해당하며, 이미지 동영상 변환을 위해 `image`와 함께 사용됩니다. 모델이 동영상 크기를 조절하는 데 사용하는 크기 조절 모드입니다. 허용되는 값은 `"pad"` (기본값) 또는 `"crop"`입니다.
`resolution`	`string` (선택사항) Veo 3 모델에만 해당합니다. 생성된 동영상의 해상도입니다. 허용되는 값은 `"720p"`(기본값) 또는 `"1080p"`입니다.
`sampleCount`	`int` 선택사항입니다. 요청된 출력 동영상 수입니다. 허용되는 값은 `1`~`4`입니다.
`seed`	`uint32` 선택사항입니다. 생성된 동영상을 결정론적으로 만드는 요청 수입니다. 다른 파라미터를 변경하지 않고 요청에 시드 수를 추가하면 모델에서 동일한 동영상을 생성합니다. 허용되는 범위는 `0`~`4,294,967,295`입니다.
`storageUri`	`string` 선택사항입니다. 출력 동영상을 저장할 Cloud Storage 버킷 URI입니다. 형식은 `gs://BUCKET_NAME/SUBDIRECTORY`입니다. Cloud Storage 버킷이 제공되지 않으면 base64로 인코딩된 동영상 바이트가 응답으로 반환됩니다.

샘플 요청

다음 예시를 사용하여 자체 동영상 요청을 만드세요.

텍스트 동영상 변환 생성 요청

REST

Vertex AI Veo API를 사용하여 텍스트 프롬프트를 테스트하려면 POST 요청을 게시자 모델 엔드포인트로 전송합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID를 나타내는 문자열입니다.
MODEL_ID: 사용할 모델 ID를 나타내는 문자열입니다. 허용되는 값은 다음과 같습니다.
- Veo 2: "veo-2.0-generate-001"
- Veo 3:"veo-3.0-generate-001"
- Veo 3:"veo-3.0-fast-generate-001"
- Veo 3:"veo-3.0-generate-preview" (미리보기)
- Veo 3:"veo-3.0-fast-generate-preview" (미리보기)
- Veo 3.1: "veo-3.1-generate-preview"
- Veo 3.1: "veo-3.1-fast-generate-preview"
TEXT_PROMPT: 동영상 생성을 안내하는 데 사용되는 텍스트 프롬프트입니다.
OUTPUT_STORAGE_URI: (선택사항) 출력 동영상을 저장할 Cloud Storage 버킷을 나타내는 문자열입니다. 제공하지 않으면 응답으로 동영상 바이트가 반환됩니다. 예를 들면 "gs://video-bucket/output/"입니다.
RESPONSE_COUNT: 생성할 동영상 파일의 수입니다. 허용되는 값의 범위는 1~4입니다.
DURATION: 생성된 동영상 파일의 길이를 나타내는 정수입니다. 각 모델에 허용되는 값은 다음과 같습니다.
- Veo 2 모델: 5~8. 기본값은 8입니다.
- Veo 3 모델: 4, 6 또는 8. 기본값은 8입니다.
추가 선택적 파라미터

사용 사례에 따라 다음 선택적 변수를 사용하세요. "parameters": {} 객체에 다음 파라미터 중 일부 또는 전부를 추가합니다.
```
"parameters": {
  "aspectRatio": "ASPECT_RATIO",
  "negativePrompt": "NEGATIVE_PROMPT",
  "personGeneration": "PERSON_SAFETY_SETTING",
  // "resolution": RESOLUTION, // Veo 3 models only
  "sampleCount": RESPONSE_COUNT,
  "seed": SEED_NUMBER
}
```
- ASPECT_RATIO: 선택사항: 생성된 동영상의 가로세로 비율을 설명하는 문자열 값입니다. 다음 값을 사용할 수 있습니다.
  - 가로 모드의 경우 "16:9"
  - 세로 모드의 경우 "9:16"
  기본값은 "16:9"입니다.
- NEGATIVE_PROMPT: 선택사항: 모델이 생성하지 않도록 하려는 콘텐츠를 설명하는 문자열 값입니다.
- PERSON_SAFETY_SETTING: 선택사항: 사람 또는 얼굴 생성의 안전 설정을 제어하는 문자열 값입니다. 다음 값을 사용할 수 있습니다.
  - "allow_adult": 성인 인물 및 얼굴만 생성합니다.
  - "disallow": 사람이나 얼굴을 생성하지 않습니다.
  기본값은 "allow_adult"입니다.
- RESOLUTION: 선택사항: 생성된 동영상의 해상도를 제어하는 문자열 값입니다. Veo 3 모델에서만 지원됩니다. 다음 값을 사용할 수 있습니다.
  - "720p"
  - "1080p"
  기본값은 "720p"입니다.
- RESPONSE_COUNT: 선택사항. 생성할 동영상 수를 설명하는 정수 값입니다. 허용되는 값의 범위는 1~4입니다.
- SEED_NUMBER: 선택사항. 모델이 결정론적 동영상을 생성하는 데 사용하는 uint32 값입니다. 다른 파라미터를 변경하지 않고 요청에 시드 수를 지정하면 모델에서 동일한 동영상을 생성합니다. 허용되는 값의 범위는 0~4294967295입니다.

HTTP 메서드 및 URL:

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning

JSON 요청 본문:

{
  "instances": [
    {
      "prompt": "TEXT_PROMPT"
    }
  ],
  "parameters": {
    "storageUri": "OUTPUT_STORAGE_URI",
    "sampleCount": "RESPONSE_COUNT"
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning"

PowerShell

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning" | Select-Object -Expand Content

이 요청은 고유한 작업 ID가 포함된 전체 작업 이름을 반환합니다. 이 전체 작업 이름을 사용하여 동영상 생성 요청 상태를 폴링합니다.

{
  "name": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/a1b07c8e-7b5a-4aba-bb34-3e1ccb8afcc8"
}

이미지 동영상 변환 생성 요청

REST

Vertex AI Veo API를 사용하여 텍스트 프롬프트를 테스트하려면 POST 요청을 게시자 모델 엔드포인트로 전송합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID를 나타내는 문자열입니다.
MODEL_ID: 사용할 모델 ID를 나타내는 문자열입니다. 허용되는 값은 다음과 같습니다.
- Veo 2:veo-2.0-generate-001
- Veo 3:veo-3.0-generate-001
- Veo 3.1:veo-3.1-generate-preview
- Veo 3.1:veo-3.1-fast-generate-preview
TEXT_PROMPT: 동영상 생성을 안내하는 데 사용되는 텍스트 프롬프트입니다.
INPUT_IMAGE: 입력 이미지를 나타내는 base64 인코딩 문자열입니다. 최상의 품질을 위해 입력 이미지의 해상도가 720p(1280x720픽셀) 이상이고 가로세로 비율이 16:9 또는 9:16인 것이 좋습니다. 이미지를 업로드할 때 가로세로 비율이나 크기가 다른 이미지는 조절되거나 중앙에서 잘릴 수 있습니다.
MIME_TYPE: 입력 이미지의 MIME 유형을 나타내는 문자열입니다. 다음 MIME 유형의 이미지만 지원됩니다.
- "image/jpeg"
- "image/png"
OUTPUT_STORAGE_URI: (선택사항) 출력 동영상을 저장할 Cloud Storage 버킷을 나타내는 문자열입니다. 제공하지 않으면 응답으로 동영상 바이트가 반환됩니다. 예를 들면 "gs://video-bucket/output/"입니다.
RESIZE_MODE: 사용할 크기 조절 모드를 나타내는 문자열입니다. 허용되는 값은 다음과 같습니다.
- "crop": 새 크기에 맞게 동영상을 자릅니다.
- "pad": 새 크기에 맞게 동영상을 패딩합니다.
RESPONSE_COUNT: 생성할 동영상 파일의 수입니다. 허용되는 값의 범위는 1~4입니다.
DURATION: 생성된 동영상 파일의 길이를 나타내는 정수입니다. 각 모델에 허용되는 값은 다음과 같습니다.
- Veo 2 모델: 5~8. 기본값은 8입니다.
- Veo 3 모델: 4, 6 또는 8. 기본값은 8입니다.
추가 선택적 파라미터

사용 사례에 따라 다음 선택적 변수를 사용하세요. "parameters": {} 객체에 다음 파라미터 중 일부 또는 전부를 추가합니다.
```
"parameters": {
  "aspectRatio": "ASPECT_RATIO",
  "negativePrompt": "NEGATIVE_PROMPT",
  "personGeneration": "PERSON_SAFETY_SETTING",
  // "resolution": RESOLUTION, // Veo 3 models only
  "sampleCount": RESPONSE_COUNT,
  "seed": SEED_NUMBER
}
```
- ASPECT_RATIO: 선택사항: 생성된 동영상의 가로세로 비율을 설명하는 문자열 값입니다. 다음 값을 사용할 수 있습니다.
  - 가로 모드의 경우 "16:9"
  - 세로 모드의 경우 "9:16"
  기본값은 "16:9"입니다.
- NEGATIVE_PROMPT: 선택사항: 모델이 생성하지 않도록 하려는 콘텐츠를 설명하는 문자열 값입니다.
- PERSON_SAFETY_SETTING: 선택사항: 사람 또는 얼굴 생성의 안전 설정을 제어하는 문자열 값입니다. 다음 값을 사용할 수 있습니다.
  - "allow_adult": 성인 인물 및 얼굴만 생성합니다.
  - "disallow": 사람이나 얼굴을 생성하지 않습니다.
  기본값은 "allow_adult"입니다.
- RESOLUTION: 선택사항: 생성된 동영상의 해상도를 제어하는 문자열 값입니다. Veo 3 모델에서만 지원됩니다. 다음 값을 사용할 수 있습니다.
  - "720p"
  - "1080p"
  기본값은 "720p"입니다.
- RESPONSE_COUNT: 선택사항. 생성할 동영상 수를 설명하는 정수 값입니다. 허용되는 값의 범위는 1~4입니다.
- SEED_NUMBER: 선택사항. 모델이 결정론적 동영상을 생성하는 데 사용하는 uint32 값입니다. 다른 파라미터를 변경하지 않고 요청에 시드 수를 지정하면 모델에서 동일한 동영상을 생성합니다. 허용되는 값의 범위는 0~4294967295입니다.

HTTP 메서드 및 URL:

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning

JSON 요청 본문:

{
  "instances": [
    {
      "prompt": "TEXT_PROMPT",
      "image": {
        "bytesBase64Encoded": "INPUT_IMAGE",
        "mimeType": "MIME_TYPE"
      }
    }
  ],
  "parameters": {
    "storageUri": "OUTPUT_STORAGE_URI",
    "sampleCount": RESPONSE_COUNT
    "resizeMode": "RESIZE_MODE"
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning" | Select-Object -Expand Content

이 요청은 고유한 작업 ID가 포함된 전체 작업 이름을 반환합니다. 이 전체 작업 이름을 사용하여 동영상 생성 요청 상태를 폴링합니다.

{
  "name": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/a1b07c8e-7b5a-4aba-bb34-3e1ccb8afcc8"
}

애셋 이미지를 사용하는 동영상 요청

REST

Vertex AI Veo API를 사용하여 텍스트 프롬프트를 테스트하려면 POST 요청을 게시자 모델 엔드포인트로 전송합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
MODEL_ID: 사용할 모델 ID를 나타내는 문자열입니다. 허용되는 값은 다음과 같습니다.
- Veo 2: veo-2.0-generate-exp
- Veo 3: veo-3.1-generate-preview
TEXT_PROMPT: 동영상 생성을 안내하는 데 사용되는 텍스트 프롬프트입니다.
BASE64_ENCODED_IMAGE: base64 바이트로 인코딩된 피사체 이미지입니다. 이 필드와 mimeType을 반복하여 최대 3개의 피사체 이미지를 지정할 수 있습니다.
IMAGE_MIME_TYPE: 입력 이미지의 MIME 유형입니다. 다음 중 하나만 사용할 수 있습니다.
- image/jpeg
- image/png
이 필드와 bytesBase64Encoded를 반복하여 최대 3개의 피사체 이미지를 지정할 수 있습니다.
OUTPUT_STORAGE_URI: (선택사항) 출력 동영상을 저장할 Cloud Storage 버킷. 제공되지 않으면 Base64 바이트로 인코딩된 동영상이 응답으로 반환됩니다. 예를 들면 gs://video-bucket/output/입니다.
RESPONSE_COUNT: 생성할 동영상 파일의 수입니다. 허용되는 정수 값: 1~4.
추가 선택적 파라미터

사용 사례에 따라 다음 선택적 변수를 사용하세요. "parameters": {} 객체에 다음 파라미터 중 일부 또는 전부를 추가합니다.
```
"parameters": {
  "aspectRatio": "ASPECT_RATIO",
  "negativePrompt": "NEGATIVE_PROMPT",
  "personGeneration": "PERSON_SAFETY_SETTING",
  // "resolution": RESOLUTION, // Veo 3 models only
  "sampleCount": RESPONSE_COUNT,
  "seed": SEED_NUMBER
}
```
- ASPECT_RATIO: 선택사항: 생성된 동영상의 가로세로 비율을 설명하는 문자열 값입니다. 다음 값을 사용할 수 있습니다.
  - 가로 모드의 경우 "16:9"
  - 세로 모드의 경우 "9:16"
  기본값은 "16:9"입니다.
- NEGATIVE_PROMPT: 선택사항: 모델이 생성하지 않도록 하려는 콘텐츠를 설명하는 문자열 값입니다.
- PERSON_SAFETY_SETTING: 선택사항: 사람 또는 얼굴 생성의 안전 설정을 제어하는 문자열 값입니다. 다음 값을 사용할 수 있습니다.
  - "allow_adult": 성인 인물 및 얼굴만 생성합니다.
  - "disallow": 사람이나 얼굴을 생성하지 않습니다.
  기본값은 "allow_adult"입니다.
- RESOLUTION: 선택사항: 생성된 동영상의 해상도를 제어하는 문자열 값입니다. Veo 3 모델에서만 지원됩니다. 다음 값을 사용할 수 있습니다.
  - "720p"
  - "1080p"
  기본값은 "720p"입니다.
- RESPONSE_COUNT: 선택사항. 생성할 동영상 수를 설명하는 정수 값입니다. 허용되는 값의 범위는 1~4입니다.
- SEED_NUMBER: 선택사항. 모델이 결정론적 동영상을 생성하는 데 사용하는 uint32 값입니다. 다른 파라미터를 변경하지 않고 요청에 시드 수를 지정하면 모델에서 동일한 동영상을 생성합니다. 허용되는 값의 범위는 0~4294967295입니다.

HTTP 메서드 및 URL:

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning

JSON 요청 본문:

{
  "instances": [
    {
      "prompt": "TEXT_PROMPT",
      // The following fields can be repeated for up to three total
      // images.
      "referenceImages": [
        {
          "image": {
            "bytesBase64Encoded": "BASE64_ENCODED_IMAGE",
            "mimeType": "IMAGE_MIME_TYPE"
          },
          "referenceType": "asset"
        }
      ]
    }
  ],
  "parameters": {
    "durationSeconds": 8,
    "storageUri": "OUTPUT_STORAGE_URI",
    "sampleCount": RESPONSE_COUNT
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning" | Select-Object -Expand Content

이 요청은 고유한 작업 ID가 포함된 전체 작업 이름을 반환합니다. 이 전체 작업 이름을 사용하여 동영상 생성 요청 상태를 폴링합니다.

{
  "name":
  "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/a1b07c8e-7b5a-4aba-bb34-3e1ccb8afcc8"
}

스타일 이미지를 사용하는 동영상 요청

REST

Vertex AI Veo API를 사용하여 텍스트 프롬프트를 테스트하려면 POST 요청을 게시자 모델 엔드포인트로 전송합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
MODEL_ID: 사용할 모델 ID를 나타내는 문자열입니다. veo-2.0-generate-exp 값을 사용합니다.

중요: Veo 3.1 모델은 referenceImages.style를 지원하지 않습니다. 스타일 이미지를 사용하는 경우 veo-2.0-generate-exp를 사용합니다.
TEXT_PROMPT: 동영상 생성을 안내하는 데 사용되는 텍스트 프롬프트입니다.
BASE64_ENCODED_IMAGE: base64 바이트로 인코딩된 스타일 이미지입니다.
IMAGE_MIME_TYPE: 입력 이미지의 MIME 유형입니다. 다음 중 하나만 사용할 수 있습니다.
- image/jpeg
- image/png
OUTPUT_STORAGE_URI: (선택사항) 출력 동영상을 저장할 Cloud Storage 버킷. 제공하지 않으면 응답으로 동영상 바이트가 반환됩니다. 예를 들면 gs://video-bucket/output/입니다.
RESPONSE_COUNT: 생성할 동영상 파일의 수입니다. 허용되는 정수 값: 1~4.
추가 선택적 파라미터

사용 사례에 따라 다음 선택적 변수를 사용하세요. "parameters": {} 객체에 다음 파라미터 중 일부 또는 전부를 추가합니다.
```
"parameters": {
  "aspectRatio": "ASPECT_RATIO",
  "negativePrompt": "NEGATIVE_PROMPT",
  "personGeneration": "PERSON_SAFETY_SETTING",
  // "resolution": RESOLUTION, // Veo 3 models only
  "sampleCount": RESPONSE_COUNT,
  "seed": SEED_NUMBER
}
```
- ASPECT_RATIO: 선택사항: 생성된 동영상의 가로세로 비율을 설명하는 문자열 값입니다. 다음 값을 사용할 수 있습니다.
  - 가로 모드의 경우 "16:9"
  - 세로 모드의 경우 "9:16"
  기본값은 "16:9"입니다.
- NEGATIVE_PROMPT: 선택사항: 모델이 생성하지 않도록 하려는 콘텐츠를 설명하는 문자열 값입니다.
- PERSON_SAFETY_SETTING: 선택사항: 사람 또는 얼굴 생성의 안전 설정을 제어하는 문자열 값입니다. 다음 값을 사용할 수 있습니다.
  - "allow_adult": 성인 인물 및 얼굴만 생성합니다.
  - "disallow": 사람이나 얼굴을 생성하지 않습니다.
  기본값은 "allow_adult"입니다.
- RESOLUTION: 선택사항: 생성된 동영상의 해상도를 제어하는 문자열 값입니다. Veo 3 모델에서만 지원됩니다. 다음 값을 사용할 수 있습니다.
  - "720p"
  - "1080p"
  기본값은 "720p"입니다.
- RESPONSE_COUNT: 선택사항. 생성할 동영상 수를 설명하는 정수 값입니다. 허용되는 값의 범위는 1~4입니다.
- SEED_NUMBER: 선택사항. 모델이 결정론적 동영상을 생성하는 데 사용하는 uint32 값입니다. 다른 파라미터를 변경하지 않고 요청에 시드 수를 지정하면 모델에서 동일한 동영상을 생성합니다. 허용되는 값의 범위는 0~4294967295입니다.

HTTP 메서드 및 URL:

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning

JSON 요청 본문:

{
  "instances": [
    {
      "prompt": "TEXT_PROMPT",
      "referenceImages": [
        {
          "image": {
            "bytesBase64Encoded": "BASE64_ENCODED_IMAGE",
            "mimeType": "IMAGE_MIME_TYPE"
          },
          "referenceType": "style"
        }
      ]
    }
  ],
  "parameters": {
    "durationSeconds": 8,
    "storageUri": "OUTPUT_STORAGE_URI",
    "sampleCount": RESPONSE_COUNT
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:predictLongRunning" | Select-Object -Expand Content

이 요청은 고유한 작업 ID가 포함된 전체 작업 이름을 반환합니다. 이 전체 작업 이름을 사용하여 동영상 생성 요청 상태를 폴링합니다.

{
  "name":
  "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/a1b07c8e-7b5a-4aba-bb34-3e1ccb8afcc8"
}

동영상 생성 장기 실행 작업의 상태 폴링

동영상 생성 장기 실행 작업의 상태를 확인합니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
MODEL_ID: 사용할 모델 ID입니다.
OPERATION_ID: 원래 동영상 생성 요청에 반환된 고유한 작업 ID입니다.

HTTP 메서드 및 URL:

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:fetchPredictOperation

JSON 요청 본문:

{
  "operationName": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/OPERATION_ID"
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:fetchPredictOperation"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID:fetchPredictOperation" | Select-Object -Expand Content

이 요청은 작업이 아직 실행 중인지 또는 완료되었는지를 비롯하여 작업에 관한 정보를 반환합니다.

응답

{
  "name": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/OPERATION_ID",
  "done": true,
  "response": {
    "raiMediaFilteredCount": 0,
    "@type": "type.googleapis.com/cloud.ai.large_models.vision.GenerateVideoResponse",
    "videos": [
      {
        "gcsUri":"gs://BUCKET_NAME/TIMESTAMPED_FOLDER/sample_0.mp4",
        "mimeType": "video/mp4"
      }
    ]
  }
}

응답 본문(동영상 요청 생성)

텍스트 동영상 변환 또는 이미지 동영상 변환 요청을 전송하면 다음과 같은 응답이 반환됩니다.

{
  "name": string
}

응답 요소	설명
`name`	동영상 생성 요청이 전송된 후 시작되는 장기 실행 작업의 전체 작업 이름입니다.

샘플 응답(동영상 생성 요청)

{
  "name": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/OPERATION_ID"
}

응답 본문(장기 실행 작업 폴링)

원래 동영상 생성 장기 실행 작업의 상태를 폴링하면 다음과 비슷한 응답이 반환됩니다.

{
   "name": string,
   "done": boolean,
   "response":{
      "@type":"type.googleapis.com/cloud.ai.large_models.vision.GenerateVideoResponse",
      "raiMediaFilteredCount": integer,
      "videos":[
         {
           "gcsUri": string,
           "mimeType": string
         },
         {
           "gcsUri": string,
           "mimeType": string
         },
         {
           "gcsUri": string,
           "mimeType": string
         },
         {
           "gcsUri": string,
           "mimeType": string
         },
      ]
   }
}

응답 요소	설명
`bytesBase64Encoded`	동영상 객체를 나타내는 Base64 바이트로 인코딩된 문자열입니다.
`done`	작업이 완료되었는지 여부를 나타내는 불리언 값입니다.
`encoding`	동영상 인코딩 유형입니다.
`gcsUri`	생성된 동영상의 Cloud Storage URI입니다.
`name`	동영상 생성 요청이 전송된 후 시작되는 장기 실행 작업의 전체 작업 이름입니다.
`raiMediaFilteredCount`	책임감 있는 AI 정책으로 인해 Veo에서 필터링된 동영상의 수를 반환합니다. 필터링된 동영상이 없으면 반환되는 개수는 `0`입니다.
`raiMediaFilteredReasons`	책임감 있는 AI 정책으로 인해 Veo에서 필터링된 동영상의 이유를 나열합니다. 자세한 내용은 안전 필터 코드 카테고리를 참조하세요.
`response`	장기 실행 작업의 응답 본문입니다.
`video`	생성된 동영상입니다.

샘플 응답(장기 실행 작업 폴링)

{
   "name": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/MODEL_ID/operations/OPERATION_ID",
   "done":true,
   "response":{
      "@type":"type.googleapis.com/cloud.ai.large_models.vision.GenerateVideoResponse",
      "raiMediaFilteredCount": 0,
      "videos":[
        {
          "gcsUri":"gs://STORAGE_BUCKET/TIMESTAMPED_SUBDIRECTORY/sample_0.mp4",
          "mimeType":"video/mp4"
        },
        {
          "gcsUri":"gs://STORAGE_BUCKET/TIMESTAMPED_SUBDIRECTORY/sample_1.mp4",
          "mimeType":"video/mp4"
        },
        {
          "gcsUri":"gs://STORAGE_BUCKET/TIMESTAMPED_SUBDIRECTORY/sample_2.mp4",
          "mimeType":"video/mp4"
        },
        {
          "gcsUri":"gs://STORAGE_BUCKET/TIMESTAMPED_SUBDIRECTORY/sample_3.mp4",
          "mimeType":"video/mp4"
        }
      ]
   }
}

추가 정보

Vertex AI에서 Veo를 사용하는 방법에 관한 자세한 내용은 Veo를 사용하여 텍스트 및 이미지 프롬프트로 동영상 생성을 참조하세요.

다음 단계

Google DeepMind의 Veo 모델에 관한 정보 읽어보기
'Veo 및 Imagen 3: Vertex AI의 새로운 동영상 및 이미지 생성 모델 발표' 블로그 게시물 읽어보기
'크리에이터를 위해 제작된 새로운 생성형 미디어 모델 및 도구' 블로그 게시물 읽어보기

Vertex AI의 Veo 동영상 생성 API 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

지원되는 모델

HTTP 요청

인스턴스

파라미터

샘플 요청

텍스트 동영상 변환 생성 요청

REST

curl

PowerShell

이미지 동영상 변환 생성 요청

REST

curl

PowerShell

애셋 이미지를 사용하는 동영상 요청

REST

curl

PowerShell

스타일 이미지를 사용하는 동영상 요청

REST

curl

PowerShell

동영상 생성 장기 실행 작업의 상태 폴링

REST

curl

PowerShell

응답

응답 본문(동영상 요청 생성)

샘플 응답(동영상 생성 요청)

응답 본문(장기 실행 작업 폴링)

샘플 응답(장기 실행 작업 폴링)

추가 정보

다음 단계

Vertex AI의 Veo 동영상 생성 API