# Veo 영상 생성 AI



3.1 standard·fast·lite와 텍스트·이미지·참조 이미지 입력으로 4·6·8초 영상을 만드는 생성 API



인증: Authorization: Bearer $APICK_API_KEY

본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다.

인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다.



## POST /rest/veo/jobs 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.job_id` (string): 접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.

- `data.model` (string): 응답을 생성한 모델 ID입니다. 요청에서 지정한 모델과 같으며, 모델 목록 API의 id 값과 비교해 확인합니다. 가능한 값은 3가지입니다. seedance = 영상 생성 제품 값입니다. 제품별 버전·등급·길이·해상도 지원 범위가 다릅니다. veo = 영상 생성 제품 값입니다. 제품별 버전·등급·길이·해상도 지원 범위가 다릅니다. kling = 영상 생성 제품 값입니다. 제품별 버전·등급·길이·해상도 지원 범위가 다릅니다. 허용값: seedance, veo, kling

- `data.version` (string): 요청한 제품의 세대·버전입니다. 같은 제품이라도 버전에 따라 지원 길이·해상도·가격이 달라지므로 견적 응답의 값과 대조하세요.

- `data.mode` (string): 영상 생성에 사용한 입력 방식입니다. text는 텍스트만, image는 이미지 1장, reference는 참조 이미지 여러 장을 쓰는 방식입니다. 가능한 값은 3가지입니다. text = 텍스트 프롬프트만으로 결과를 만드는 값입니다. 이미지 입력 없이 문장 묘사만 사용합니다. image = 이미지 1장을 첫 프레임·기준 이미지로 쓰는 값입니다. 이미지와 프롬프트를 함께 보냅니다. reference = 참조 이미지·영상을 스타일 기준으로 쓰는 값입니다. 여러 장을 보낼 수 있고, 제품별 최대 장수가 다릅니다. 허용값: text, image, reference

- `data.tier` (string): 영상 생성 품질 등급입니다. 등급이 높을수록 해상도·디테일이 좋아지고 초당 포인트 단가도 높아집니다.

- `data.status` (string): 현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다. 가능한 값은 4가지입니다. waiting = 접수만 되고 처리는 시작되지 않은 상태입니다. 결과가 비어 있으므로 같은 작업 ID로 잠시 후 다시 조회합니다. processing = 처리 중인 상태입니다. 결과가 아직 확정되지 않았으므로 완료 상태가 될 때까지 조회를 반복합니다. completed = 정상 완료된 상태입니다. 결과 필드나 파일 경로에서 실제 결과를 사용할 수 있습니다. failed = 작업이 실패한 상태입니다. error의 code·message로 원인을 확인하고 재시도 가능 여부를 판단합니다. 허용값: waiting, processing, completed, failed

- `data.duration` (integer): 요청한 영상 길이(초)입니다. 제품·등급별 허용 범위가 다르며, 접수 후에는 변경할 수 없습니다.

- `data.aspect_ratio` (string): 출력 영상의 가로:세로 비율입니다. 예: 16:9, 9:16, 1:1. 입력 이미지 비율과 다르면 일부가 잘릴 수 있습니다.

- `data.resolution` (string): 출력 영상의 해상도입니다. 720p·1080p 등 제품별 지원 값이 다르며, 높을수록 포인트 단가가 높아집니다.

- `data.audio` (boolean): 영상에 오디오를 함께 생성했는지 여부입니다. false면 무음 영상이며, 제품에 따라 오디오 생성이 지원되지 않을 수 있습니다. true = 오디오가 포함된 영상을 만든 경우, false = 무음 영상인 경우입니다. 제품이 오디오 생성을 지원하지 않으면 항상 false입니다.

- `data.point_per_second` (number): 접수 시 적용한 초당 포인트 단가입니다. 영상 길이와 곱하면 차감 포인트를 계산할 수 있으며, 실시간 견적 여부에 따라 달라집니다.

- `data.charged_point` (number): 최종 차감된 포인트입니다. 실패·부분 성공 시 환급이 반영된 값입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.result_available` (boolean): 결과 파일을 지금 내려받을 수 있는지 여부입니다. false면 아직 처리 중이거나 결과가 만료·삭제된 상태입니다. true = 결과 파일을 지금 내려받을 수 있는 경우, false = 처리 중이거나 실패·만료된 경우입니다.

- `data.result_expires_at` (string): 결과 만료 ISO 8601 일시. 결과가 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `data.result_url` (string): 완료·미만료 상태에서만 제공되는 에이픽 결과 다운로드 주소. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.created_at` (string): 작업이 접수된 일시입니다. ISO 8601 형식이며, 결과 만료 시각을 계산할 때 기준으로 사용합니다.

- `data.completed_at` (string): 작업이 완료된 일시입니다. 완료 전에는 null이며, 처리 시간을 계산할 때 created_at과 함께 사용합니다. null 허용.

- `data.error` (object): 작업 실패 원인을 담은 객체입니다. 공개 오류코드(code)와 사람이 읽을 설명(message)이 들어 있으며, 성공한 작업에는 없습니다.

- `data.error.code` (string): 작업 실패의 공개 오류코드입니다. 같은 코드는 같은 원인을 뜻하며, 재시도 가능 여부는 오류 문서를 확인하세요.

- `data.error.message` (string): 작업 실패 내용을 사람이 읽을 수 있게 설명합니다. 상세 원인은 서버 로그에만 남으며, 고객에게는 이 문구를 안내하세요. null 허용.

- `data.idempotent_replay` (boolean): 같은 멱등 키로 기존 작업을 반환하면 true. 재전송의 api.cost는 0입니다. true = 같은 멱등 키로 기존 작업을 그대로 돌려준 경우(재전송이라 추가 차감 없음), false = 새로 처리한 경우입니다.

- `data.price_source` (string): 신규 접수 단가 기준. live=실시간 견적, table=기본 단가표. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. 가능한 값은 2가지입니다. live = 접수 시점의 실시간 견적으로 단가를 정한 경우입니다. 같은 요청이라도 견적이 바뀌면 단가가 달라질 수 있습니다. table = 실시간 견적을 받지 못해 기본 단가표로 계산한 경우입니다. 실제 차감액은 api.cost로 확인하세요. 허용값: live, table

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (number): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

## 작업 접수: POST /rest/veo/jobs



### 입력

- `prompt` (string, 필수): 생성할 영상의 장면·동작·카메라 움직임을 설명합니다. 최대 2,000자이며, 구체적인 피사체와 배경을 적을수록 의도에 가까운 결과가 나옵니다.

- `version` (string, 선택): 영상 모델 버전. 생략 시 3.1. 등급·해상도·길이·오디오·파일 제약과 요금은 선택 버전별 개발가이드 표를 확인하세요. 이 경로에서는 항상 "3.1" 하나만 오는 고정값입니다. 허용값: 3.1

- `mode` (string, 선택): 입력 방식 — 'text'(텍스트만) | 'image'(첫 프레임 이미지 지정) | 'reference'(참조 이미지·영상으로 주체 지정). 기본 text 가능한 값은 3가지입니다. text = 텍스트 프롬프트만으로 결과를 만드는 값입니다. 이미지 입력 없이 문장 묘사만 사용합니다. image = 이미지 1장을 첫 프레임·기준 이미지로 쓰는 값입니다. 이미지와 프롬프트를 함께 보냅니다. reference = 참조 이미지·영상을 스타일 기준으로 쓰는 값입니다. 여러 장을 보낼 수 있고, 제품별 최대 장수가 다릅니다. 허용값: text, image, reference

- `tier` (string, 선택): 품질·속도 등급. 지원 등급과 생략 시 기본값은 version과 mode에 따라 다릅니다. 가능한 값은 3가지입니다. standard = 표준 품질·속도 등급입니다. 대부분 제품의 기본값이며 품질과 처리 시간의 균형을 맞춘 등급입니다. fast = 빠른 생성 등급입니다. 표준보다 처리 시간이 짧고 화질은 다소 낮거나 같은 수준입니다. lite = 가장 가벼운 등급입니다. 해상도·길이 등 지원 범위가 좁고 단가가 가장 낮습니다. 허용값: standard, fast, lite

- `duration` (integer, 선택): 영상 길이(초), 전체 버전 범위 4~8. 허용 값과 기본값은 버전·등급별로 다릅니다.

- `aspect_ratio` (string, 선택): 출력 영상의 가로:세로 비율입니다. 예: 16:9, 9:16, 1:1. 선택한 버전·등급·모드에서 허용하는 값만 사용할 수 있으며, 다른 값은 접수 전에 거부됩니다. 가능한 값은 2가지입니다. 16:9 = 가로가 긴 와이드 비율입니다. 유튜브·TV처럼 가로 화면에 맞습니다. 9:16 = 세로로 긴 비율입니다. 숏폼·모바일 세로 화면에 맞습니다. 허용값: 16:9, 9:16

- `resolution` (string, 선택): 출력 해상도. 전체 버전의 값 목록이며 허용 조합·기본값·요금은 버전별 개발가이드를 따릅니다. 가능한 값은 3가지입니다. 720p = 가로 1280픽셀급의 HD 해상도입니다. 일반적인 웹 재생에 적합합니다. 1080p = 가로 1920픽셀급의 Full HD 해상도입니다. 화질을 우선할 때 사용하며 단가가 더 높습니다. 4k = 가로 3840픽셀급의 4K UHD 해상도입니다. 가장 선명하지만 파일 용량과 단가가 가장 큽니다. 허용값: 720p, 1080p, 4k

- `audio` (boolean, 선택): 오디오 생성 여부. 선택 가능한 버전은 기본 true, 무음 전용 버전은 false, 오디오 필수 버전은 true만 허용합니다. true = 오디오가 포함된 영상을 만든 경우, false = 무음 영상인 경우입니다. 제품이 오디오 생성을 지원하지 않으면 항상 false입니다.

- `negative_prompt` (string, 선택): 결과에서 빼고 싶은 요소를 적습니다. 예: text, watermark, blurry. negative_prompt를 지원하지 않는 제품에서는 무시됩니다.

- `seed` (integer, 선택): 같은 결과를 다시 만들기 위한 시드입니다. 같은 프롬프트·설정에서 시드가 같으면 비슷한 결과가 나오며, 생략하면 매번 달라집니다.

- `idempotency_key` (string, 선택): 같은 요청을 다시 보낼 때 중복 접수·과금을 막는 고유 키입니다. 요청 내용이 같으면 같은 키를 유지하고, 내용이 바뀌면 새 키를 만드세요.

- `image` (file, 조건부): 분석할 이미지 파일입니다. JPG·PNG·WEBP를 지원하며, 파일 크기·해상도 제한은 요청 표를 확인하세요.

- `last_image` (file, 선택): image 모드에서 마지막 프레임 이미지 1장. multipart/form-data로 전송하며, 파일 경로가 아니라 파일 본문을 첨부합니다.

- `reference_image` (file, 조건부): reference 모드 필수. 주체를 참조할 이미지 1~3장. multipart/form-data로 전송하며, 파일 경로가 아니라 파일 본문을 첨부합니다.



### 응답 명세

```json

{
  "type": "object",
  "description": "공개 JSON 응답.",
  "properties": {
    "data": {
      "description": "영상 작업 공개 상태. 처리 단계에서 제공되는 항목만 포함합니다.",
      "type": "object",
      "properties": {
        "job_id": {
          "type": "string",
          "description": "접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다."
        },
        "model": {
          "type": "string",
          "description": "요청한 영상 제품.",
          "enum": [
            "seedance",
            "veo",
            "kling"
          ]
        },
        "version": {
          "type": "string",
          "description": "선택한 제품 버전."
        },
        "mode": {
          "type": "string",
          "description": "입력 방식.",
          "enum": [
            "text",
            "image",
            "reference"
          ]
        },
        "tier": {
          "type": "string",
          "description": "선택한 생성 등급."
        },
        "status": {
          "type": "string",
          "description": "현재 작업 상태.",
          "enum": [
            "waiting",
            "processing",
            "completed",
            "failed"
          ]
        },
        "duration": {
          "type": "integer",
          "description": "요청 영상 길이(초)."
        },
        "aspect_ratio": {
          "type": "string",
          "description": "영상 화면 비율."
        },
        "resolution": {
          "type": "string",
          "description": "영상 해상도."
        },
        "audio": {
          "type": "boolean",
          "description": "오디오 생성 여부."
        },
        "point_per_second": {
          "type": "number",
          "description": "접수 시 적용한 초당 포인트."
        },
        "charged_point": {
          "type": "number",
          "description": "접수 시 차감한 전체 포인트."
        },
        "result_available": {
          "type": "boolean",
          "description": "결과가 완료되어 다운로드 가능한지 여부."
        },
        "result_expires_at": {
          "type": "string",
          "description": "결과 만료 ISO 8601 일시. 결과가 없으면 null.",
          "nullable": true
        },
        "result_url": {
          "type": "string",
          "description": "완료·미만료 상태에서만 제공되는 에이픽 결과 다운로드 주소."
        },
        "created_at": {
          "type": "string",
          "description": "작업 생성 일시."
        },
        "completed_at": {
          "type": "string",
          "description": "작업 완료 일시. 완료 전에는 null일 수 있습니다.",
          "nullable": true
        },
        "error": {
          "type": "object",
          "description": "실패한 작업에만 포함합니다.",
          "properties": {
            "code": {
              "type": "string",
              "description": "작업 실패의 공개 오류코드."
            },
            "message": {
              "type": "string",
              "description": "실패 내용. 설명이 없으면 null.",
              "nullable": true
            }
          }
        },
        "idempotent_replay": {
          "type": "boolean",
          "description": "같은 멱등 키로 기존 작업을 반환하면 true. 재전송의 api.cost는 0입니다."
        },
        "price_source": {
          "type": "string",
          "description": "신규 접수 단가 기준. live=실시간 견적, table=기본 단가표.",
          "enum": [
            "live",
            "table"
          ]
        }
      }
    },
    "api": {
      "type": "object",
      "description": "호출 메타데이터.",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "API 공통 처리 여부. HTTP 상태·업무 결과와 함께 확인합니다."
        },
        "cost": {
          "type": "number",
          "description": "이번 호출에서 차감한 포인트. 무료 조회·재전송은 0."
        },
        "pl_id": {
          "type": "integer",
          "description": "과금 기록 ID. 과금 기록이 있을 때만 포함합니다."
        }
      }
    }
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "job_id": "a1b2c3d4e5f647a8b9c0d1e2f3a4b5c6",
    "status": "waiting",
    "model": "veo",
    "mode": "text",
    "version": "3.1",
    "tier": "standard",
    "duration": 8,
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "audio": true,
    "point_per_second": 900,
    "charged_point": 7200,
    "price_source": "live"
  },
  "api": {
    "success": true,
    "cost": 7200
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "job_id": "a1b2c3d4e5f647a8b9c0d1e2f3a4b5c6",
    "model": "veo",
    "version": "3.1",
    "mode": "text",
    "tier": "standard",
    "status": "completed",
    "duration": 8,
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "audio": true,
    "point_per_second": 900,
    "charged_point": 7200,
    "result_available": true,
    "result_expires_at": "2026-10-28T12:00:00.000Z",
    "result_url": "https://apick.app/rest/veo/jobs/a1b2c3d4e5f647a8b9c0d1e2f3a4b5c6/result",
    "created_at": "2026-10-21T11:56:00.000Z",
    "completed_at": "2026-10-21T12:00:00.000Z"
  },
  "api": {
    "success": true,
    "cost": 0
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "job_id": "a1b2c3d4e5f647a8b9c0d1e2f3a4b5c6",
    "status": "failed",
    "result_available": false,
    "result_expires_at": null,
    "error": {
      "code": "APICK_VIDEO_GENERATION_FAILED",
      "message": "영상 생성에 실패했습니다. 포인트는 환불되었습니다."
    }
  },
  "api": {
    "success": true,
    "cost": 0
  }
}

```

### curl

```curl

curl --fail-with-body --request POST 'https://apick.app/rest/veo/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'prompt=안개 낀 새벽 숲을 가로지르는 드론 샷, 시네마틱 조명' \
  --form-string 'duration=8' \
  --form-string 'resolution=1080p'

```

### Node.js (서버 ESM)

```javascript

const form = new FormData();
form.append("prompt", "안개 낀 새벽 숲을 가로지르는 드론 샷, 시네마틱 조명");
form.append("duration", "8");
form.append("resolution", "1080p");
const response = await fetch("https://apick.app/rest/veo/jobs", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

```

### python

```python

import os
import requests
parts = [
    ("prompt", (None, "안개 낀 새벽 숲을 가로지르는 드론 샷, 시네마틱 조명")),
    ("duration", (None, "8")),
    ("resolution", (None, "1080p")),
]
response = requests.request("POST", "https://apick.app/rest/veo/jobs",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'prompt' => '안개 낀 새벽 숲을 가로지르는 드론 샷, 시네마틱 조명',
    'duration' => '8',
    'resolution' => '1080p',
];
$curl = curl_init('https://apick.app/rest/veo/jobs');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

```

## GET /rest/veo/jobs/:job_id 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.job_id` (string): 접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.

- `data.model` (string): 응답을 생성한 모델 ID입니다. 요청에서 지정한 모델과 같으며, 모델 목록 API의 id 값과 비교해 확인합니다. 가능한 값은 3가지입니다. seedance = 영상 생성 제품 값입니다. 제품별 버전·등급·길이·해상도 지원 범위가 다릅니다. veo = 영상 생성 제품 값입니다. 제품별 버전·등급·길이·해상도 지원 범위가 다릅니다. kling = 영상 생성 제품 값입니다. 제품별 버전·등급·길이·해상도 지원 범위가 다릅니다. 허용값: seedance, veo, kling

- `data.version` (string): 요청한 제품의 세대·버전입니다. 같은 제품이라도 버전에 따라 지원 길이·해상도·가격이 달라지므로 견적 응답의 값과 대조하세요.

- `data.mode` (string): 영상 생성에 사용한 입력 방식입니다. text는 텍스트만, image는 이미지 1장, reference는 참조 이미지 여러 장을 쓰는 방식입니다. 가능한 값은 3가지입니다. text = 텍스트 프롬프트만으로 결과를 만드는 값입니다. 이미지 입력 없이 문장 묘사만 사용합니다. image = 이미지 1장을 첫 프레임·기준 이미지로 쓰는 값입니다. 이미지와 프롬프트를 함께 보냅니다. reference = 참조 이미지·영상을 스타일 기준으로 쓰는 값입니다. 여러 장을 보낼 수 있고, 제품별 최대 장수가 다릅니다. 허용값: text, image, reference

- `data.tier` (string): 영상 생성 품질 등급입니다. 등급이 높을수록 해상도·디테일이 좋아지고 초당 포인트 단가도 높아집니다.

- `data.status` (string): 현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다. 가능한 값은 4가지입니다. waiting = 접수만 되고 처리는 시작되지 않은 상태입니다. 결과가 비어 있으므로 같은 작업 ID로 잠시 후 다시 조회합니다. processing = 처리 중인 상태입니다. 결과가 아직 확정되지 않았으므로 완료 상태가 될 때까지 조회를 반복합니다. completed = 정상 완료된 상태입니다. 결과 필드나 파일 경로에서 실제 결과를 사용할 수 있습니다. failed = 작업이 실패한 상태입니다. error의 code·message로 원인을 확인하고 재시도 가능 여부를 판단합니다. 허용값: waiting, processing, completed, failed

- `data.duration` (integer): 요청한 영상 길이(초)입니다. 제품·등급별 허용 범위가 다르며, 접수 후에는 변경할 수 없습니다.

- `data.aspect_ratio` (string): 출력 영상의 가로:세로 비율입니다. 예: 16:9, 9:16, 1:1. 입력 이미지 비율과 다르면 일부가 잘릴 수 있습니다.

- `data.resolution` (string): 출력 영상의 해상도입니다. 720p·1080p 등 제품별 지원 값이 다르며, 높을수록 포인트 단가가 높아집니다.

- `data.audio` (boolean): 영상에 오디오를 함께 생성했는지 여부입니다. false면 무음 영상이며, 제품에 따라 오디오 생성이 지원되지 않을 수 있습니다. true = 오디오가 포함된 영상을 만든 경우, false = 무음 영상인 경우입니다. 제품이 오디오 생성을 지원하지 않으면 항상 false입니다.

- `data.point_per_second` (number): 접수 시 적용한 초당 포인트 단가입니다. 영상 길이와 곱하면 차감 포인트를 계산할 수 있으며, 실시간 견적 여부에 따라 달라집니다.

- `data.charged_point` (number): 최종 차감된 포인트입니다. 실패·부분 성공 시 환급이 반영된 값입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.result_available` (boolean): 결과 파일을 지금 내려받을 수 있는지 여부입니다. false면 아직 처리 중이거나 결과가 만료·삭제된 상태입니다. true = 결과 파일을 지금 내려받을 수 있는 경우, false = 처리 중이거나 실패·만료된 경우입니다.

- `data.result_expires_at` (string): 결과 만료 ISO 8601 일시. 결과가 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `data.result_url` (string): 완료·미만료 상태에서만 제공되는 에이픽 결과 다운로드 주소. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.created_at` (string): 작업이 접수된 일시입니다. ISO 8601 형식이며, 결과 만료 시각을 계산할 때 기준으로 사용합니다.

- `data.completed_at` (string): 작업이 완료된 일시입니다. 완료 전에는 null이며, 처리 시간을 계산할 때 created_at과 함께 사용합니다. null 허용.

- `data.error` (object): 작업 실패 원인을 담은 객체입니다. 공개 오류코드(code)와 사람이 읽을 설명(message)이 들어 있으며, 성공한 작업에는 없습니다.

- `data.error.code` (string): 작업 실패의 공개 오류코드입니다. 같은 코드는 같은 원인을 뜻하며, 재시도 가능 여부는 오류 문서를 확인하세요.

- `data.error.message` (string): 작업 실패 내용을 사람이 읽을 수 있게 설명합니다. 상세 원인은 서버 로그에만 남으며, 고객에게는 이 문구를 안내하세요. null 허용.

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (number): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

## 상태·목록 조회: GET /rest/veo/jobs/:job_id



### 입력



### 응답 명세

```json

{
  "type": "object",
  "description": "공개 JSON 응답.",
  "properties": {
    "data": {
      "description": "영상 작업 공개 상태. 처리 단계에서 제공되는 항목만 포함합니다.",
      "type": "object",
      "properties": {
        "job_id": {
          "type": "string",
          "description": "접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다."
        },
        "model": {
          "type": "string",
          "description": "요청한 영상 제품.",
          "enum": [
            "seedance",
            "veo",
            "kling"
          ]
        },
        "version": {
          "type": "string",
          "description": "선택한 제품 버전."
        },
        "mode": {
          "type": "string",
          "description": "입력 방식.",
          "enum": [
            "text",
            "image",
            "reference"
          ]
        },
        "tier": {
          "type": "string",
          "description": "선택한 생성 등급."
        },
        "status": {
          "type": "string",
          "description": "현재 작업 상태.",
          "enum": [
            "waiting",
            "processing",
            "completed",
            "failed"
          ]
        },
        "duration": {
          "type": "integer",
          "description": "요청 영상 길이(초)."
        },
        "aspect_ratio": {
          "type": "string",
          "description": "영상 화면 비율."
        },
        "resolution": {
          "type": "string",
          "description": "영상 해상도."
        },
        "audio": {
          "type": "boolean",
          "description": "오디오 생성 여부."
        },
        "point_per_second": {
          "type": "number",
          "description": "접수 시 적용한 초당 포인트."
        },
        "charged_point": {
          "type": "number",
          "description": "접수 시 차감한 전체 포인트."
        },
        "result_available": {
          "type": "boolean",
          "description": "결과가 완료되어 다운로드 가능한지 여부."
        },
        "result_expires_at": {
          "type": "string",
          "description": "결과 만료 ISO 8601 일시. 결과가 없으면 null.",
          "nullable": true
        },
        "result_url": {
          "type": "string",
          "description": "완료·미만료 상태에서만 제공되는 에이픽 결과 다운로드 주소."
        },
        "created_at": {
          "type": "string",
          "description": "작업 생성 일시."
        },
        "completed_at": {
          "type": "string",
          "description": "작업 완료 일시. 완료 전에는 null일 수 있습니다.",
          "nullable": true
        },
        "error": {
          "type": "object",
          "description": "실패한 작업에만 포함합니다.",
          "properties": {
            "code": {
              "type": "string",
              "description": "작업 실패의 공개 오류코드."
            },
            "message": {
              "type": "string",
              "description": "실패 내용. 설명이 없으면 null.",
              "nullable": true
            }
          }
        }
      }
    },
    "api": {
      "type": "object",
      "description": "호출 메타데이터.",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "API 공통 처리 여부. HTTP 상태·업무 결과와 함께 확인합니다."
        },
        "cost": {
          "type": "number",
          "description": "이번 호출에서 차감한 포인트. 무료 조회·재전송은 0."
        },
        "pl_id": {
          "type": "integer",
          "description": "과금 기록 ID. 과금 기록이 있을 때만 포함합니다."
        }
      }
    }
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "job_id": "a1b2c3d4e5f647a8b9c0d1e2f3a4b5c6",
    "model": "veo",
    "version": "3.1",
    "mode": "text",
    "tier": "standard",
    "status": "completed",
    "duration": 8,
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "audio": true,
    "point_per_second": 900,
    "charged_point": 7200,
    "result_available": true,
    "result_expires_at": "2026-10-28T12:00:00.000Z",
    "result_url": "https://apick.app/rest/veo/jobs/a1b2c3d4e5f647a8b9c0d1e2f3a4b5c6/result",
    "created_at": "2026-10-21T11:56:00.000Z",
    "completed_at": "2026-10-21T12:00:00.000Z"
  },
  "api": {
    "success": true,
    "cost": 0
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "job_id": "a1b2c3d4e5f647a8b9c0d1e2f3a4b5c6",
    "status": "failed",
    "result_available": false,
    "result_expires_at": null,
    "error": {
      "code": "APICK_VIDEO_GENERATION_FAILED",
      "message": "영상 생성에 실패했습니다. 포인트는 환불되었습니다."
    }
  },
  "api": {
    "success": true,
    "cost": 0
  }
}

```

### curl

```curl

curl --fail-with-body --request GET "https://apick.app/rest/veo/jobs/${APICK_JOB_ID}" \
  --header "Authorization: Bearer $APICK_API_KEY"

```

### Node.js (서버 ESM)

```javascript

const response = await fetch(`https://apick.app/rest/veo/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}`, {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

```

### python

```python

import os
import requests
from urllib.parse import quote
response = requests.request("GET", "https://apick.app" + "/rest/veo/jobs/{job_id}".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")),
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/veo/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

```

## GET /rest/veo/jobs/:job_id/result 응답 필드

## 결과 받기: GET /rest/veo/jobs/:job_id/result



### 입력



### 응답 명세

```json

{
  "type": "string",
  "format": "binary"
}

```

### curl

```curl

curl --fail-with-body --request GET "https://apick.app/rest/veo/jobs/${APICK_JOB_ID}/result" \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --dump-header response.headers --output result.mp4
# response.headers의 Content-Type을 확인한 뒤 파일을 사용하세요.

```

### Node.js (서버 ESM)

```javascript

const response = await fetch(`https://apick.app/rest/veo/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}/result`, {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
if ((response.headers.get("content-type") || "").includes("json")) {
  throw new Error(JSON.stringify(await response.json()));
}
const { writeFile } = await import("node:fs/promises");
await writeFile("result.mp4", new Uint8Array(await response.arrayBuffer()));

```

### python

```python

import os
import requests
from urllib.parse import quote
response = requests.request("GET", "https://apick.app" + "/rest/veo/jobs/{job_id}/result".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")),
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120), stream=True)
response.raise_for_status()
if "json" in response.headers.get("Content-Type", ""):
    raise RuntimeError(response.json())
with open("result.mp4", "wb") as output:
    for chunk in response.iter_content(65536):
        output.write(chunk)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/veo/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '/result');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$type = curl_getinfo($curl, CURLINFO_CONTENT_TYPE) ?: "";
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
if (strpos($type, "json") !== false) { throw new RuntimeException($body); }
file_put_contents('result.mp4', $body);

```

## 사용 예시 1. 8초 1080p 영상

텍스트만으로 고해상도 영상을 만듭니다. 1080p·4k는 8초만 됩니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/veo/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'prompt=안개 낀 새벽 숲을 가로지르는 드론 샷, 시네마틱 조명' \
  --form-string 'duration=8' \
  --form-string 'resolution=1080p'

```

- HTTP 202와 `data.job_id`를 받고, `data.charged_point`(8초 × 초당 포인트)가 예약 차감됩니다.

## 사용 예시 2. 첫 프레임 이미지로 6초 영상

이미지에서 시작해 카메라가 움직이는 영상을 만듭니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/veo/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'mode=image' \
  --form 'image=@./first_frame.jpg' \
  --form-string 'prompt=카메라가 서서히 줌아웃되며 전경이 드러나는 장면' \
  --form-string 'duration=6'

```

- 이미지는 PNG·JPEG·WebP, 128~8,192px, 종횡비 0.25~4, 50MB 이하여야 합니다.

## 사용 예시 3. 참조 이미지 2장으로 주체 지정

제품이나 인물 이미지를 1~3장 첨부해 같은 주체가 나오게 합니다. 참조 모드는 8초만 됩니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/veo/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'mode=reference' \
  --form 'reference_image=@./bottle_front.png' \
  --form 'reference_image=@./bottle_side.png' \
  --form-string 'prompt=참조 이미지의 물병이 계곡 바위 위에 놓이고 물방울이 맺히는 광고 장면' \
  --form-string 'duration=8'

```

- `reference` 모드는 `standard` 등급만 됩니다. `aspect_ratio`는 보내도 반영되지 않습니다.

## 사용 예시 4. 빠른 시안: fast 등급 4초

시안을 빠르게 여러 개 볼 때 짧은 길이와 `fast` 등급을 쓰고, 원하지 않는 요소는 `negative_prompt`로 뺍니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/veo/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'prompt=안개 낀 새벽 숲을 가로지르는 드론 샷' \
  --form-string 'tier=fast' \
  --form-string 'duration=4' \
  --form-string 'resolution=720p' \
  --form-string 'negative_prompt=사람, 글자, 로고' \
  --form-string 'seed=42'

```

- 같은 `seed`와 입력으로 다시 접수하면 비슷한 결과를 얻기 쉽습니다. 새 접수는 다시 예약 차감됩니다.

## 사용 예시 5. 진행 조회

접수한 `job_id`로 진행 상황을 조회합니다.

```bash

curl --fail-with-body --request GET "https://apick.app/rest/veo/jobs/${APICK_JOB_ID}" \
  --header "Authorization: Bearer $APICK_API_KEY"

```

- `data.status`가 `completed`면 `data.result_url`로 MP4를 내려받고, `failed`면 `data.error.code`를 확인합니다(포인트는 환불됨).

- `waiting`·`processing`이면 5초 뒤 다시 조회합니다. 조회는 무료입니다.

## 코드·오류

- APICK_VIDEO_AUTH_FAILED (401): 인증에 실패했습니다.

- APICK_VIDEO_ACCESS_DISABLED (403): API 이용이 제한된 계정입니다.

- APICK_VIDEO_PAYMENT_REQUIRED (403): 최소 1회 결제 후 이용할 수 있습니다.

- APICK_VIDEO_POINTS_INSUFFICIENT (402): 사용 가능한 포인트가 부족합니다.

- APICK_VIDEO_INVALID_REQUEST (400): 요청 내용을 확인해 주세요.

- APICK_VIDEO_PROMPT_REQUIRED (400): prompt를 입력해 주세요.

- APICK_VIDEO_PROMPT_TOO_LONG (400): prompt는 최대 2,000자입니다.

- APICK_VIDEO_MODE_INVALID (400): mode는 text, image, reference 중 하나여야 합니다.

- APICK_VIDEO_MODE_NOT_SUPPORTED (400): 이 모델에서는 지원하지 않는 mode입니다.

- APICK_VIDEO_DURATION_INVALID (400): duration 값이 허용 범위를 벗어났습니다.

- APICK_VIDEO_ASPECT_RATIO_INVALID (400): aspect_ratio 값이 허용 목록에 없습니다.

- APICK_VIDEO_RESOLUTION_INVALID (400): resolution 값이 허용 목록에 없습니다.

- APICK_VIDEO_TIER_INVALID (400): tier 값이 허용 목록에 없습니다.

- APICK_VIDEO_VERSION_INVALID (400): 지원하지 않는 영상 모델 버전입니다.

- APICK_VIDEO_OPTION_NOT_SUPPORTED (400): 이 모델·mode에서는 지원하지 않는 옵션입니다.

- APICK_VIDEO_SOURCE_REQUIRED (400): 이 mode에는 입력 파일이 필요합니다.

- APICK_VIDEO_SOURCE_TOO_MANY (400): 입력 파일 개수가 허용 범위를 초과했습니다.

- APICK_VIDEO_SOURCE_INVALID (400): 입력 파일 형식이나 크기를 확인해 주세요.

- APICK_VIDEO_IDEMPOTENCY_CONFLICT (409): 같은 idempotency_key에 다른 요청을 사용할 수 없습니다.

- APICK_VIDEO_TOO_MANY_ACTIVE_JOBS (429): 동시에 진행할 수 있는 작업 수를 초과했습니다.

- APICK_VIDEO_CONTENT_REJECTED (422): 요청한 영상을 생성할 수 없습니다. 프롬프트나 입력 파일을 확인해 주세요.

- APICK_VIDEO_RATE_LIMITED (429): 현재 요청이 많습니다. 잠시 후 다시 시도해 주세요.

- APICK_VIDEO_TEMPORARILY_UNAVAILABLE (503): 현재 영상 서비스를 이용할 수 없습니다. 잠시 후 다시 시도해 주세요.

- APICK_VIDEO_TIMEOUT (408): 처리 시간이 초과됐습니다. 포인트는 환불되었습니다.

- APICK_VIDEO_GENERATION_FAILED (500): 영상 생성에 실패했습니다. 포인트는 환불되었습니다.

- APICK_VIDEO_JOB_NOT_FOUND (404): 작업을 찾을 수 없습니다.

- APICK_VIDEO_JOB_CONFLICT (409): 현재 작업 상태에서는 요청을 처리할 수 없습니다.

- APICK_VIDEO_RESULT_EXPIRED (410): 결과 보관 기간이 만료되었습니다.

- APICK_VIDEO_RESULT_INVALID (502): 생성 결과를 확인할 수 없습니다.

- APICK_VIDEO_BILLING_FAILED (424): 결제 원장을 완료하지 못했습니다.

- APICK_VIDEO_INTERNAL_ERROR (500): 영상 서비스 내부 오류가 발생했습니다.

## 상세 기능·요금

지원 버전 한눈에 보기 버전지원 생성 방식과 최대 길이 3.1 · 기본 버전텍스트→영상 · 이미지+텍스트→영상 · 참조 이미지+텍스트→영상최대 8초 연동 흐름 작업을 접수하고, 진행 상황을 조회하다가, 완료되면 MP4 파일을 내려받습니다. 접수 후에는 취소할 수 없으며, 실패하거나 처리 시간이 초과되면 예약된 포인트가 자동으로 전액 환불됩니다. MethodURL기능성공 결과 POST/rest/veo/jobs영상 작업 접수HTTP 202와 job_id GET/rest/veo/jobs/{job_id}진행 조회(무료)HTTP 200과 현재 status GET/rest/veo/jobs/{job_id}/resultMP4 다운로드(무료, Range 지원)<job_id>.mp4 결과 다운로드 result_available이 true일 때 GET /rest/veo/jobs/{job_id}/result를 인증 헤더와 함께 호출하면 video/mp4 파일을 받습니다. 완료 후 7일 동안 반복해서 내려받을 수 있고, Range 헤더로 일부 구간만 받을 수 있습니다(HTTP 206). 기간이 지나면 APICK_VIDEO_RESULT_EXPIRED(410)입니다. 요금 등급초당 포인트5초 예시 standard900P4,500P fast360P1,800P 접수 시 duration × 초당 포인트를 예약 차감합니다. 완료되면 그대로 확정되고, 실패하거나 처리 시간이 초과되면 전액 환불됩니다. 진행 조회와 다운로드는 무료입니다. MCP veo_jobs_create로 작업을 접수하고 veo_jobs_status로 진행 상황을 조회합니다. 영상 파일은 MCP 응답으로 직접 받지 않고, 진행 조회 응답의 result_url로 REST 다운로드합니다. 자세한 내용은 MCP 연동 가이드와 /mcp/ai를 확인하세요. 업로드 용량 제한: 100MB multipart/form-data 요청에 포함된 입력 이미지·참조 영상·참조 오디오의 합계는 최대 100MB입니다. 이미지는 PNG·JPEG·WebP, 영상은 MP4·MOV·WebM, 오디오는 MP3·WAV를 지원하며 모델별 개수·해상도·종횡비 제약은 가이드의 파라미터 표를 따릅니다. 제한을 초과하면 HTTP 413과 REQUEST_TOO_LARGE 오류가 반환되며 과금되지 않습니다.

## 상세 요청

입력 방식부터 고르기 같은 제품이라도 버전에 따라 받을 수 있는 소재가 다릅니다. 여기서 ‘영상 참조’는 기존 영상을 그대로 편집하는 기능이 아니라, 업로드한 영상의 동작과 흐름을 참고해 새 영상을 만드는 기능입니다. 원하는 작업선택할 모드와 입력 텍스트로 영상 생성mode=text · prompt만 입력 이미지로 영상 생성mode=image · 첫 프레임 이미지와 텍스트 입력, 지원 버전은 마지막 프레임도 선택 가능 영상으로 영상 생성mode=reference · 참조 영상을 받아 새 영상을 만드는 버전만 가능 여러 소재로 영상 생성mode=reference · 지원 버전에서 참조 이미지·영상·오디오를 조합해 입력 버전별 세부 옵션과 요금 version은 선택 입력입니다. 생략하면 3.1을 사용하며 다른 버전으로 자동 변경하지 않습니다. 아래 표의 모드·등급 조합만 사용할 수 있습니다. 기존 요청 설명은 기본 버전 기준이며 다른 버전은 이 표를 따릅니다. 요금은 접수 시점에 실시간으로 확정됩니다. 표의 금액은 기준 단가이며, 실제 차감 포인트는 접수 응답의 charged_point·point_per_second로 확인할 수 있습니다. 버전 · 모드 · 등급지원 옵션과 초당 포인트 3.1 · 텍스트→영상 (text) · standard 길이4초 · 6초 · 8초기본 8초 해상도·요금720p900P/초1080p900P/초4k900P/초 화면 비율16:9 · 9:16 오디오선택 가능 (기본 true) 길이 제한1080p · 4k 해상도는 8초만 허용 추가 옵션negative_prompt, seed 3.1 · 텍스트→영상 (text) · fast 길이4초 · 6초 · 8초기본 8초 해상도·요금720p360P/초1080p360P/초4k360P/초 화면 비율16:9 · 9:16 오디오선택 가능 (기본 true) 길이 제한1080p · 4k 해상도는 8초만 허용 추가 옵션negative_prompt, seed 3.1 · 텍스트→영상 (text) · lite 길이4초 · 6초 · 8초기본 8초 해상도·요금720p230P/초1080p230P/초 화면 비율16:9 · 9:16 오디오항상 포함 (audio=true) 길이 제한1080p · 4k 해상도는 8초만 허용 추가 옵션seed 3.1 · 이미지+텍스트→영상 (image) · standard 길이4초 · 6초 · 8초기본 8초 해상도·요금720p900P/초1080p900P/초4k900P/초 화면 비율16:9 · 9:16 오디오선택 가능 (기본 true) 마지막 프레임선택 가능 길이 제한1080p · 4k 해상도는 8초만 허용 추가 옵션negative_prompt, seed 3.1 · 이미지+텍스트→영상 (image) · fast 길이4초 · 6초 · 8초기본 8초 해상도·요금720p360P/초1080p360P/초4k360P/초 화면 비율16:9 · 9:16 오디오선택 가능 (기본 true) 마지막 프레임선택 가능 길이 제한1080p · 4k 해상도는 8초만 허용 추가 옵션negative_prompt, seed 3.1 · 이미지+텍스트→영상 (image) · lite 길이4초 · 6초 · 8초기본 8초 해상도·요금720p230P/초1080p230P/초 화면 비율16:9 · 9:16 오디오항상 포함 (audio=true) 마지막 프레임선택 가능 길이 제한1080p · 4k 해상도는 8초만 허용 추가 옵션seed 3.1 · 참조 소재→영상 (reference) · standard 길이4초 · 6초 · 8초기본 8초 해상도·요금720p900P/초1080p900P/초4k900P/초 화면 비율입력 이미지 기준, 지정값 무시 오디오선택 가능 (기본 true) 참조 이미지1~3개 길이 제한720p · 1080p · 4k 해상도는 8초만 허용 추가 옵션negative_prompt, seed 요청 예: {"version":"3.1","mode":"text","prompt":"바닷가를 달리는 자전거"}. 생성·상태 응답의 version에서 실제 선택 버전을 확인할 수 있습니다. 미지원 버전은 APICK_VIDEO_VERSION_INVALID, 미지원 옵션 조합은 해당 옵션 오류로 과금 전에 거절됩니다. 요청 — 작업 접수 form-data로 보냅니다. 파일은 같은 요청에 첨부하며, 같은 항목 이름을 반복하면 여러 파일이 됩니다(예: reference_image 3번). 표의 범위는 기본 버전 기준이며 다른 버전은 위 버전별 표를 따릅니다. 지원하지 않는 옵션·조합은 과금 전에 거절됩니다. 이미지는 PNG·JPEG·WebP, 가로·세로 128~8,192px, 종횡비 0.25~4, 50MB 이하입니다. 참조 영상·오디오는 받지 않습니다. cfg_scale을 보내면 APICK_VIDEO_OPTION_NOT_SUPPORTED로 거절됩니다. form-data 전체 예제 보기

## 상세 응답

응답 — 접수와 진행 조회 접수 응답과 진행 조회 응답은 같은 필드를 씁니다. 진행 조회는 5초 간격을 권장하며, status가 completed나 failed가 되면 멈춥니다. 필드타입설명 data.job_idString작업 ID. 진행 조회·다운로드 경로에 넣습니다. data.statusStringwaiting(대기)·processing(제작 중)·completed(완료)·failed(실패, 환불됨) data.versionString실제로 쓴 버전 data.point_per_secondNumber적용된 초당 포인트 data.charged_pointNumber접수 때 예약 차감한 전체 포인트(duration × 초당 포인트) data.result_availableBooleantrue면 지금 내려받을 수 있습니다. data.result_urlString완료 후 다운로드 주소. 인증 헤더를 붙여 요청합니다. data.result_expires_atString/null다운로드 만료 시각(완료 후 7일) data.error.codeString실패 시 오류 코드. 사유는 data.error.message data.idempotent_replayBoolean같은 idempotency_key로 이미 접수된 작업을 돌려준 경우 true(이때 api.cost는 0) { "data": { "job_id": "a1b2c3d4e5f647a8b9c0d1e2f3a4b5c6", "status": "waiting", "model": "veo", "mode": "text", "version": "3.1", "tier": "standard", "duration": 8, "aspect_ratio": "16:9", "resolution": "1080p", "audio": true, "point_per_second": 900, "charged_point": 7200, "price_source": "live" }, "api": { "success": true, "cost": 7200 } } { "data": { "job_id": "a1b2c3d4e5f647a8b9c0d1e2f3a4b5c6", "model": "veo", "version": "3.1", "mode": "text", "tier": "standard", "status": "completed", "duration": 8, "aspect_ratio": "16:9", "resolution": "1080p", "audio": true, "point_per_second": 900, "charged_point": 7200, "result_available": true, "result_expires_at": "2026-10-28T12:00:00.000Z", "result_url": "https://apick.app/rest/veo/jobs/a1b2c3d4e5f647a8b9c0d1e2f3a4b5c6/result", "created_at": "2026-10-21T11:56:00.000Z", "completed_at": "2026-10-21T12:00:00.000Z" }, "api": { "success": true, "cost": 0 } } { "data": { "job_id": "a1b2c3d4e5f647a8b9c0d1e2f3a4b5c6", "status": "failed", "result_available": false, "result_expires_at": null, "error": { "code": "APICK_VIDEO_GENERATION_FAILED", "message": "영상 생성에 실패했습니다. 포인트는 환불되었습니다." } }, "api": { "success": true, "cost": 0 } }

## 상세 코드·정책

오류 대처 코드대처 APICK_VIDEO_DURATION_INVALIDduration은 4·6·8만 됩니다. reference 모드나 1080p·4k이면 8로 보내세요. APICK_VIDEO_CONTENT_REJECTED프롬프트·입력 파일·생성된 오디오가 정책(저작권·안전) 검수에서 거부됐습니다. 예약 포인트는 환불됩니다. 표현을 바꾸거나, 오디오 때문이라면 audio=false로 다시 접수하세요(지원 버전). APICK_VIDEO_TOO_MANY_ACTIVE_JOBS동시에 진행할 수 있는 작업 수를 넘었습니다. 진행 중인 작업이 끝난 뒤 접수하세요. APICK_VIDEO_OPTION_NOT_SUPPORTED선택한 버전·모드에서 지원하지 않는 옵션입니다(예: cfg_scale). 위 버전별 표의 '추가 옵션'을 확인하세요. APICK_VIDEO_IDEMPOTENCY_CONFLICT같은 idempotency_key로 다른 내용을 보냈습니다. 새 작업에는 새 키를 쓰세요. APICK_VIDEO_TIMEOUT · APICK_VIDEO_GENERATION_FAILED포인트는 환불됐습니다. 같은 내용으로 다시 접수할 수 있으며, 새 접수는 다시 예약 차감됩니다. APICK_VIDEO_RATE_LIMITED · APICK_VIDEO_TEMPORARILY_UNAVAILABLE접수되지 않았습니다. Retry-After 헤더가 있으면 그 시간 뒤에 다시 보내세요.

## 상세 예제

호출 예시 같은 요청을 JavaScript와 Python으로 옮긴 예시입니다. 키는 환경변수 APICK_API_KEY 에서 읽습니다. JavaScript 예시 form-data 전체 예제 보기 Python 예시 form-data 전체 예제 보기