# Seedance 영상 생성 AI



1.0·1.5·2.0·2.5 버전과 텍스트·이미지·참조 영상 입력으로 최대 30초 영상을 만드는 생성 API



인증: Authorization: Bearer $APICK_API_KEY

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

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



## POST /rest/seedance/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/seedance/jobs



### 입력

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

- `version` (string, 선택): 영상 모델 버전. 생략 시 2.5. 등급·해상도·길이·오디오·파일 제약과 요금은 선택 버전별 개발가이드 표를 확인하세요. 가능한 값은 4가지입니다. 2.5 = 2.5 버전을 선택한 값입니다. 같은 제품이라도 버전별 지원 등급·길이·해상도·오디오·요금이 다르므로 이 문서의 버전 표와 대조하세요. 2.0 = 2.0 버전을 선택한 값입니다. 같은 제품이라도 버전별 지원 등급·길이·해상도·오디오·요금이 다르므로 이 문서의 버전 표와 대조하세요. 1.5 = 1.5 버전을 선택한 값입니다. 같은 제품이라도 버전별 지원 등급·길이·해상도·오디오·요금이 다르므로 이 문서의 버전 표와 대조하세요. 1.0 = 1.0 버전을 선택한 값입니다. 같은 제품이라도 버전별 지원 등급·길이·해상도·오디오·요금이 다르므로 이 문서의 버전 표와 대조하세요. 허용값: 2.5, 2.0, 1.5, 1.0

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

- `tier` (string, 선택): 품질·속도 등급. 지원 등급과 생략 시 기본값은 version과 mode에 따라 다릅니다. 가능한 값은 4가지입니다. standard = 표준 품질·속도 등급입니다. 대부분 제품의 기본값이며 품질과 처리 시간의 균형을 맞춘 등급입니다. fast = 빠른 생성 등급입니다. 표준보다 처리 시간이 짧고 화질은 다소 낮거나 같은 수준입니다. mini = 경량 등급입니다. 짧은 영상·낮은 해상도에 맞춘 저비용 등급입니다. pro = 상위 품질 등급입니다. 표준보다 화질·디테일이 좋고 처리 시간과 요금이 더 큽니다. 허용값: standard, fast, mini, pro

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

- `aspect_ratio` (string, 선택): 출력 영상의 가로:세로 비율입니다. 예: 16:9, 9:16, 1:1. 선택한 버전·등급·모드에서 허용하는 값만 사용할 수 있으며, 다른 값은 접수 전에 거부됩니다. 가능한 값은 7가지입니다. 16:9 = 가로가 긴 와이드 비율입니다. 유튜브·TV처럼 가로 화면에 맞습니다. 4:3 = 가로가 약간 긴 전통적인 화면 비율입니다. 일반 사진·강의 영상에 맞습니다. 1:1 = 가로·세로가 같은 정사각 비율입니다. 피드·프로필 이미지에 맞습니다. 3:4 = 세로가 약간 긴 비율입니다. 인쇄·세로 사진에 맞습니다. 9:16 = 세로로 긴 비율입니다. 숏폼·모바일 세로 화면에 맞습니다. 21:9 = 매우 넓은 시네마 비율입니다. 영화 같은 와이드 화면에 맞습니다. adaptive = 입력 이미지·영상의 비율을 그대로 따라가는 값입니다. 원본 비율을 유지해야 할 때 쓰며, 지원 제품과 버전이 제한됩니다. 허용값: 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive

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

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

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

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

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

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

- `reference_image` (file, 조건부): reference 모드에서 주체·스타일을 참조할 이미지. 기본 버전 0~30장.

- `reference_video` (file, 조건부): reference 모드에서 동작을 참조할 영상. 기본 버전 0~10개. MP4·MOV·WebM.

- `reference_audio` (file, 조건부): reference 모드에서 음악·목소리·효과음을 참조할 오디오. 기본 버전 0~10개. MP3·WAV.



### 응답 명세

```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": "7f7e43f578cd459db04696416435c789",
    "status": "waiting",
    "model": "seedance",
    "mode": "text",
    "version": "2.5",
    "tier": "standard",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "audio": true,
    "point_per_second": 1250,
    "charged_point": 6250,
    "price_source": "live"
  },
  "api": {
    "success": true,
    "cost": 6250
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "job_id": "7f7e43f578cd459db04696416435c789",
    "model": "seedance",
    "version": "2.5",
    "mode": "text",
    "tier": "standard",
    "status": "completed",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "audio": true,
    "point_per_second": 1250,
    "charged_point": 6250,
    "result_available": true,
    "result_expires_at": "2026-10-28T12:00:00.000Z",
    "result_url": "https://apick.app/rest/seedance/jobs/7f7e43f578cd459db04696416435c789/result",
    "created_at": "2026-10-21T11:55:00.000Z",
    "completed_at": "2026-10-21T12:00:00.000Z"
  },
  "api": {
    "success": true,
    "cost": 0
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "job_id": "7f7e43f578cd459db04696416435c789",
    "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/seedance/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'prompt=해 질 녘 해안 도로를 달리는 오픈카, 부드러운 카메라 팬' \
  --form-string 'duration=5' \
  --form-string 'aspect_ratio=16:9'

```

### Node.js (서버 ESM)

```javascript

const form = new FormData();
form.append("prompt", "해 질 녘 해안 도로를 달리는 오픈카, 부드러운 카메라 팬");
form.append("duration", "5");
form.append("aspect_ratio", "16:9");
const response = await fetch("https://apick.app/rest/seedance/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, "5")),
    ("aspect_ratio", (None, "16:9")),
]
response = requests.request("POST", "https://apick.app/rest/seedance/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' => '5',
    'aspect_ratio' => '16:9',
];
$curl = curl_init('https://apick.app/rest/seedance/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/seedance/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/seedance/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": "7f7e43f578cd459db04696416435c789",
    "model": "seedance",
    "version": "2.5",
    "mode": "text",
    "tier": "standard",
    "status": "completed",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "audio": true,
    "point_per_second": 1250,
    "charged_point": 6250,
    "result_available": true,
    "result_expires_at": "2026-10-28T12:00:00.000Z",
    "result_url": "https://apick.app/rest/seedance/jobs/7f7e43f578cd459db04696416435c789/result",
    "created_at": "2026-10-21T11:55:00.000Z",
    "completed_at": "2026-10-21T12:00:00.000Z"
  },
  "api": {
    "success": true,
    "cost": 0
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "job_id": "7f7e43f578cd459db04696416435c789",
    "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/seedance/jobs/${APICK_JOB_ID}" \
  --header "Authorization: Bearer $APICK_API_KEY"

```

### Node.js (서버 ESM)

```javascript

const response = await fetch(`https://apick.app/rest/seedance/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/seedance/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/seedance/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/seedance/jobs/:job_id/result 응답 필드

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



### 입력



### 응답 명세

```json

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

```

### curl

```curl

curl --fail-with-body --request GET "https://apick.app/rest/seedance/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/seedance/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/seedance/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/seedance/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. 세로형 숏폼 영상

텍스트만으로 9:16 세로 영상을 만듭니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/seedance/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'prompt=비 오는 밤 네온사인 골목을 천천히 걷는 고양이, 낮은 카메라 시점' \
  --form-string 'duration=5' \
  --form-string 'aspect_ratio=9:16'

```

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

## 사용 예시 2. 첫 프레임 이미지로 영상 만들기

가진 이미지에서 시작하는 영상을 만듭니다. 화면 비율은 입력 이미지를 따릅니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/seedance/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'mode=image' \
  --form 'image=@./first_frame.png' \
  --form-string 'prompt=인물이 천천히 뒤돌아보며 미소 짓는 장면' \
  --form-string 'duration=5'

```

- 이미지가 300~6,000px, 종횡비 0.4~2.5, 30MB 이하가 아니면 `APICK_VIDEO_SOURCE_INVALID`로 접수 전에 거절됩니다.

## 사용 예시 3. 참조 이미지·영상으로 주체와 동작 지정

등장인물 이미지와 동작 참고 영상을 함께 첨부합니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/seedance/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'mode=reference' \
  --form 'reference_image=@./character.png' \
  --form 'reference_video=@./dance.mp4' \
  --form-string 'prompt=참조 이미지의 인물이 참조 영상과 같은 춤 동작을 해변에서 하는 장면' \
  --form-string 'duration=8'

```

- 버전마다 첨부 개수 한도가 다르니 위 버전별 표의 참조 이미지·영상 개수를 확인합니다.

## 사용 예시 4. 1080p 무음 영상, 재전송 대비

배경음을 따로 넣을 영상은 `audio=false`로 만들고, 네트워크 재전송에 대비해 `idempotency_key`를 붙입니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/seedance/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'aspect_ratio=16:9' \
  --form-string 'prompt=해 질 녘 해안 도로를 달리는 오픈카, 부드러운 카메라 팬' \
  --form-string 'duration=5' \
  --form-string 'resolution=1080p' \
  --form-string 'audio=false' \
  --form-string 'idempotency_key=promo-20261021-0001'

```

- 응답을 못 받았으면 같은 키·같은 내용으로 다시 보내세요. `data.idempotent_replay`가 `true`이고 `api.cost`는 0입니다.

- 1080p는 초당 포인트가 더 큽니다. `data.point_per_second`로 확인합니다.

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

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

```bash

curl --fail-with-body --request GET "https://apick.app/rest/seedance/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): 영상 서비스 내부 오류가 발생했습니다.

## 상세 기능·요금

지원 버전 한눈에 보기 버전지원 생성 방식과 최대 길이 2.5 · 기본 버전텍스트→영상 · 이미지+텍스트→영상 · 참조 이미지+텍스트→영상 · 참조 영상+텍스트→영상 · 이미지+텍스트+참조 영상→영상 · 참조 오디오+텍스트→영상최대 30초 2.0텍스트→영상 · 이미지+텍스트→영상 · 참조 이미지+텍스트→영상 · 참조 영상+텍스트→영상 · 이미지+텍스트+참조 영상→영상 · 참조 오디오+텍스트→영상최대 15초 1.5텍스트→영상 · 이미지+텍스트→영상최대 12초 1.0텍스트→영상 · 이미지+텍스트→영상최대 12초 연동 흐름 작업을 접수하고, 진행 상황을 조회하다가, 완료되면 MP4 파일을 내려받습니다. 접수 후에는 취소할 수 없으며, 실패하거나 처리 시간이 초과되면 예약된 포인트가 자동으로 전액 환불됩니다. MethodURL기능성공 결과 POST/rest/seedance/jobs영상 작업 접수HTTP 202와 job_id GET/rest/seedance/jobs/{job_id}진행 조회(무료)HTTP 200과 현재 status GET/rest/seedance/jobs/{job_id}/resultMP4 다운로드(무료, Range 지원)<job_id>.mp4 결과 다운로드 result_available이 true일 때 GET /rest/seedance/jobs/{job_id}/result를 인증 헤더와 함께 호출하면 video/mp4 파일을 받습니다. 완료 후 7일 동안 반복해서 내려받을 수 있고, Range 헤더로 일부 구간만 받을 수 있습니다(HTTP 206). 기간이 지나면 APICK_VIDEO_RESULT_EXPIRED(410)입니다. 요금 등급·해상도초당 포인트5초 예시 480p560P2,800P 720p1,250P6,250P 1080p2,810P14,050P 접수 시 duration × 초당 포인트를 예약 차감합니다(해상도에 따라 초당 포인트가 다릅니다). 완료되면 그대로 확정되고, 실패하거나 처리 시간이 초과되면 전액 환불됩니다. 진행 조회와 다운로드는 무료입니다. MCP seedance_jobs_create로 작업을 접수하고 seedance_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은 선택 입력입니다. 생략하면 2.5을 사용하며 다른 버전으로 자동 변경하지 않습니다. 아래 표의 모드·등급 조합만 사용할 수 있습니다. 기존 요청 설명은 기본 버전 기준이며 다른 버전은 이 표를 따릅니다. 요금은 접수 시점에 실시간으로 확정됩니다. 표의 금액은 기준 단가이며, 실제 차감 포인트는 접수 응답의 charged_point·point_per_second로 확인할 수 있습니다. 버전 · 모드 · 등급지원 옵션과 초당 포인트 2.5 · 텍스트→영상 (text) · standard 길이4~30초기본 5초 해상도·요금480p560P/초720p1,250P/초1080p2,810P/초 화면 비율16:9 · 4:3 · 1:1 · 3:4 · 9:16 · 21:9 · adaptive 오디오선택 가능 (기본 true) 추가 옵션없음 2.5 · 이미지+텍스트→영상 (image) · standard 길이4~30초기본 5초 해상도·요금480p560P/초720p1,250P/초1080p2,810P/초 화면 비율16:9 · 4:3 · 1:1 · 3:4 · 9:16 · 21:9 · adaptive 오디오선택 가능 (기본 true) 마지막 프레임선택 가능 추가 옵션없음 2.5 · 참조 소재→영상 (reference) · standard 길이4~30초기본 5초 해상도·요금480p560P/초720p1,250P/초1080p2,810P/초 화면 비율16:9 · 4:3 · 1:1 · 3:4 · 9:16 · 21:9 · adaptive 오디오선택 가능 (기본 true) 참조 이미지0~30개 참조 영상최대 10개 참조 오디오최대 10개 · MP3·WAV 추가 옵션없음 2.0 · 텍스트→영상 (text) · standard 길이4~15초기본 5초 해상도·요금480p490P/초720p1,090P/초 화면 비율16:9 · 9:16 오디오선택 가능 (기본 true) 추가 옵션없음 2.0 · 텍스트→영상 (text) · fast 길이4~15초기본 5초 해상도·요금480p400P/초720p880P/초 화면 비율16:9 · 9:16 오디오선택 가능 (기본 true) 추가 옵션없음 2.0 · 텍스트→영상 (text) · mini 길이4~15초기본 5초 해상도·요금480p260P/초720p260P/초 화면 비율21:9 · 16:9 · 4:3 · 1:1 · 3:4 · 9:16 · adaptive 오디오선택 가능 (기본 true) 추가 옵션없음 2.0 · 이미지+텍스트→영상 (image) · standard 길이4~15초기본 5초 해상도·요금480p490P/초720p1,090P/초 화면 비율16:9 · 9:16 오디오선택 가능 (기본 true) 마지막 프레임선택 가능 추가 옵션없음 2.0 · 이미지+텍스트→영상 (image) · fast 길이4~15초기본 5초 해상도·요금480p400P/초720p880P/초 화면 비율16:9 · 9:16 오디오선택 가능 (기본 true) 마지막 프레임선택 가능 추가 옵션없음 2.0 · 이미지+텍스트→영상 (image) · mini 길이4~15초기본 5초 해상도·요금480p260P/초720p260P/초 화면 비율21:9 · 16:9 · 4:3 · 1:1 · 3:4 · 9:16 · adaptive 오디오선택 가능 (기본 true) 마지막 프레임선택 가능 추가 옵션없음 2.0 · 참조 소재→영상 (reference) · standard 길이4~15초기본 5초 해상도·요금480p490P/초720p1,090P/초 화면 비율16:9 · 9:16 오디오선택 가능 (기본 true) 참조 이미지0~9개 참조 영상최대 3개 참조 오디오최대 3개 · MP3·WAV 추가 옵션없음 2.0 · 참조 소재→영상 (reference) · fast 길이4~15초기본 5초 해상도·요금480p400P/초720p880P/초 화면 비율16:9 · 9:16 오디오선택 가능 (기본 true) 참조 이미지0~9개 참조 영상최대 3개 참조 오디오최대 3개 · MP3·WAV 추가 옵션없음 2.0 · 참조 소재→영상 (reference) · mini 길이4~15초기본 5초 해상도·요금480p260P/초720p260P/초 화면 비율21:9 · 16:9 · 4:3 · 1:1 · 3:4 · 9:16 · adaptive 오디오선택 가능 (기본 true) 참조 이미지0~9개 참조 영상최대 3개 참조 오디오최대 3개 · MP3·WAV 추가 옵션없음 1.5 · 텍스트→영상 (text) · pro 길이4~12초기본 5초 해상도·요금720p220P/초 화면 비율21:9 · 16:9 · 4:3 · 1:1 · 3:4 · 9:16 오디오선택 가능 (기본 true) 추가 옵션seed 1.5 · 텍스트→영상 (text) · fast 길이4~12초기본 5초 해상도·요금720p90P/초 화면 비율21:9 · 16:9 · 4:3 · 1:1 · 3:4 · 9:16 오디오선택 가능 (기본 true) 추가 옵션seed 1.5 · 이미지+텍스트→영상 (image) · pro 길이4~12초기본 5초 해상도·요금720p220P/초 화면 비율21:9 · 16:9 · 4:3 · 1:1 · 3:4 · 9:16 오디오선택 가능 (기본 true) 마지막 프레임선택 가능 추가 옵션seed 1.5 · 이미지+텍스트→영상 (image) · fast 길이4~12초기본 5초 해상도·요금720p90P/초 화면 비율21:9 · 16:9 · 4:3 · 1:1 · 3:4 · 9:16 오디오선택 가능 (기본 true) 마지막 프레임선택 가능 추가 옵션seed 1.0 · 텍스트→영상 (text) · pro 길이2~12초기본 5초 해상도·요금480p100P/초720p220P/초1080p500P/초 화면 비율21:9 · 16:9 · 4:3 · 1:1 · 3:4 · 9:16 오디오미지원 (audio=false) 추가 옵션seed 1.0 · 텍스트→영상 (text) · fast 길이2~12초기본 5초 해상도·요금480p50P/초 화면 비율21:9 · 16:9 · 4:3 · 1:1 · 3:4 · 9:16 오디오미지원 (audio=false) 추가 옵션seed 1.0 · 이미지+텍스트→영상 (image) · pro 길이2~12초기본 5초 해상도·요금480p100P/초720p220P/초1080p500P/초 화면 비율21:9 · 16:9 · 4:3 · 1:1 · 3:4 · 9:16 오디오미지원 (audio=false) 마지막 프레임선택 가능 추가 옵션seed 1.0 · 이미지+텍스트→영상 (image) · fast 길이2~12초기본 5초 해상도·요금480p50P/초 화면 비율21:9 · 16:9 · 4:3 · 1:1 · 3:4 · 9:16 오디오미지원 (audio=false) 추가 옵션seed 요청 예: {"version":"2.5","mode":"text","prompt":"바닷가를 달리는 자전거"}. 생성·상태 응답의 version에서 실제 선택 버전을 확인할 수 있습니다. 미지원 버전은 APICK_VIDEO_VERSION_INVALID, 미지원 옵션 조합은 해당 옵션 오류로 과금 전에 거절됩니다. 요청 — 작업 접수 form-data로 보냅니다. 파일은 같은 요청에 첨부하며, 같은 항목 이름을 반복하면 여러 파일이 됩니다(예: reference_image 3번). 표의 범위는 기본 버전 기준이며 다른 버전은 위 버전별 표를 따릅니다. 지원하지 않는 옵션·조합은 과금 전에 거절됩니다. 이미지는 PNG·JPEG·WebP·BMP·TIFF·GIF, 가로·세로 300~6,000px, 종횡비 0.4~2.5, 30MB 이하입니다. 2.0 Standard·Fast·Mini는 이미지 9개·영상 3개·오디오 3개까지이며, 오디오를 쓸 때 이미지나 영상도 1개 이상 있어야 합니다. 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": "7f7e43f578cd459db04696416435c789", "status": "waiting", "model": "seedance", "mode": "text", "version": "2.5", "tier": "standard", "duration": 5, "aspect_ratio": "16:9", "resolution": "720p", "audio": true, "point_per_second": 1250, "charged_point": 6250, "price_source": "live" }, "api": { "success": true, "cost": 6250 } } { "data": { "job_id": "7f7e43f578cd459db04696416435c789", "model": "seedance", "version": "2.5", "mode": "text", "tier": "standard", "status": "completed", "duration": 5, "aspect_ratio": "16:9", "resolution": "720p", "audio": true, "point_per_second": 1250, "charged_point": 6250, "result_available": true, "result_expires_at": "2026-10-28T12:00:00.000Z", "result_url": "https://apick.app/rest/seedance/jobs/7f7e43f578cd459db04696416435c789/result", "created_at": "2026-10-21T11:55:00.000Z", "completed_at": "2026-10-21T12:00:00.000Z" }, "api": { "success": true, "cost": 0 } } { "data": { "job_id": "7f7e43f578cd459db04696416435c789", "status": "failed", "result_available": false, "result_expires_at": null, "error": { "code": "APICK_VIDEO_GENERATION_FAILED", "message": "영상 생성에 실패했습니다. 포인트는 환불되었습니다." } }, "api": { "success": true, "cost": 0 } }

## 상세 코드·정책

오류 대처 코드대처 APICK_VIDEO_CONTENT_REJECTED프롬프트·입력 파일·생성된 오디오가 정책(저작권·안전) 검수에서 거부됐습니다. 예약 포인트는 환불됩니다. 표현을 바꾸거나, 오디오 때문이라면 audio=false로 다시 접수하세요. APICK_VIDEO_TOO_MANY_ACTIVE_JOBS동시에 진행할 수 있는 작업 수를 넘었습니다. 진행 중인 작업이 끝난 뒤 접수하세요. APICK_VIDEO_OPTION_NOT_SUPPORTED선택한 버전·모드에서 지원하지 않는 옵션입니다. 위 버전별 표의 '추가 옵션'을 확인하세요. 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 전체 예제 보기