> ## Documentation Index
> Fetch the complete documentation index at: https://wand.tencentpoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# COS

> COS 객체 업로드, 다운로드, 목록 조회 API Reference

MPS 태스크의 입력/출력 파일은 Tencent Cloud COS에 저장됩니다. 로컬 파일 업로드, 결과 파일 다운로드, Bucket 내 객체 목록 조회 방법을 설명합니다.

## 요청 방법

| 항목         | 값                                                       |
| ---------- | ------------------------------------------------------- |
| API Action | `PUT Object`(업로드), `GET Object`(다운로드), `GET Bucket`(목록) |
| 엔드포인트      | `https://<Bucket>.cos.<Region>.myqcloud.com`            |
| 인증         | COS XML API 서명(SecretId/SecretKey 기반)                   |
| 요청 방식      | HTTP PUT / GET                                          |

COS API는 동기 API로 즉시 결과를 반환합니다. MPS 태스크와 달리 TaskId 발급/폴링 과정이 없습니다.

## 요청 파라미터

### 업로드 (PUT Object)

| 파라미터   | 타입     | 필수 여부 | 예시                | 설명                                                        |
| ------ | ------ | ----- | ----------------- | --------------------------------------------------------- |
| Bucket | String | 필수    | `mybucket-125xxx` | 대상 COS Bucket 이름. 환경 변수 `TENCENTCLOUD_COS_BUCKET`으로 대체 가능 |
| Region | String | 필수    | `ap-guangzhou`    | Bucket 리전. 환경 변수 `TENCENTCLOUD_COS_REGION`으로 대체 가능        |
| Key    | String | 필수    | `input/video.mp4` | 객체 키. 생략 시 `input/<로컬 파일명>` 규칙을 권장                        |
| 로컬 파일  | File   | 필수    | `./video.mp4`     | 업로드할 로컬 파일 경로                                             |

### 다운로드 (GET Object)

| 파라미터     | 타입     | 필수 여부 | 예시                  | 설명                       |
| -------- | ------ | ----- | ------------------- | ------------------------ |
| Bucket   | String | 필수    | `mybucket-125xxx`   | 대상 COS Bucket 이름         |
| Region   | String | 필수    | `ap-guangzhou`      | Bucket 리전                |
| Key      | String | 필수    | `output/result.mp4` | 다운로드할 객체 키               |
| 로컬 저장 경로 | String | 선택    | `./result.mp4`      | 저장 경로. 생략 시 `./<객체 파일명>` |

### 목록 조회 (GET Bucket)

| 파라미터    | 타입      | 필수 여부 | 예시                  | 설명                           |
| ------- | ------- | ----- | ------------------- | ---------------------------- |
| Bucket  | String  | 필수    | `mybucket-125xxx`   | 대상 COS Bucket 이름             |
| Region  | String  | 필수    | `ap-guangzhou`      | Bucket 리전                    |
| Prefix  | String  | 선택    | `output/transcode/` | 경로 접두사 필터. 생략 시 루트부터 조회      |
| MaxKeys | Integer | 선택    | `50`                | 최대 반환 객체 수. 기본 1000, 최대 1000 |

## 응답 파라미터

| 파라미터     | 타입              | 필수 여부 | 예시                                                                      | 설명                                     |
| -------- | --------------- | ----- | ----------------------------------------------------------------------- | -------------------------------------- |
| ETag     | String          | 업로드 시 | `"9e107d9d372bb6826bd81d3542a419d6"`                                    | 업로드된 객체의 ETag                          |
| 객체 URL   | String          | 항상    | `https://mybucket-125xxx.cos.ap-guangzhou.myqcloud.com/input/video.mp4` | 객체 접근 URL. 사전 서명 URL은 유효 기간 내 다운로드에 사용 |
| Contents | Array of Object | 목록 시  | -                                                                       | 객체 목록. Key, Size, LastModified 등 포함    |

## 호출 예시

```python theme={null}
# 업로드, 다운로드, 목록 조회 (qcloud_cos SDK)
from qcloud_cos import CosConfig, CosS3Client

config = CosConfig(Region="ap-guangzhou", SecretId="<SecretId>", SecretKey="<SecretKey>")
client = CosS3Client(config)

# 업로드: Key 생략 규칙은 input/<파일명>
client.upload_file(
    Bucket="mybucket-125xxx",
    LocalFilePath="./video.mp4",
    Key="input/video.mp4"
)

# 다운로드
client.download_file(
    Bucket="mybucket-125xxx",
    Key="output/result.mp4",
    DestFilePath="./result.mp4"
)

# 목록 조회: output/transcode/ 아래 최대 50개
resp = client.list_objects(
    Bucket="mybucket-125xxx",
    Prefix="output/transcode/",
    MaxKeys=50
)
for obj in resp.get("Contents", []):
    print(obj["Key"], obj["Size"])
```

```python theme={null}
# 사전 서명 다운로드 URL 생성 (기본 유효 기간 내 사용)
url = client.get_presigned_url(
    Method="GET",
    Bucket="mybucket-125xxx",
    Key="output/result.mp4",
    Expired=3600
)
print(url)
```

## 응답 예시

```json theme={null}
{
  "Contents": [
    {
      "Key": "output/transcode/video.mp4",
      "Size": "52428800",
      "LastModified": "2026-03-18T07:30:02.000Z",
      "ETag": "\"9e107d9d372bb6826bd81d3542a419d6\""
    },
    {
      "Key": "output/transcode/video_hd.mp4",
      "Size": "83886080",
      "LastModified": "2026-03-18T08:12:44.000Z",
      "ETag": "\"5d41402abc4b2a76b9719d911017c592\""
    }
  ],
  "IsTruncated": "false",
  "MaxKeys": "50",
  "Prefix": "output/transcode/"
}
```

## 주의사항

<Warning>
  업로드 시 Key를 지정하지 않으면 `input/<로컬 파일명>` 규칙을 사용하고, 다운로드 시 로컬 경로를 지정하지 않으면 `./<객체 파일명>`으로 저장합니다. 경로 규칙을 명시하지 않아도 되지만, MPS 입력 규약(`input/` 접두사)은 유지하세요.
</Warning>

<Note>
  Bucket과 Region은 환경 변수 `TENCENTCLOUD_COS_BUCKET` / `TENCENTCLOUD_COS_REGION`으로 주입하는 것을 권장합니다. MPS API의 `InputInfo`/`OutputStorage`에 전달하는 Bucket/Region/Object 값과 동일한 값을 사용해야 태스크가 파일을 찾을 수 있습니다.
</Note>

<Note>
  목록 조회의 `MaxKeys`는 1000이 상한입니다. 파일명 검색(부분 일치/정확 일치)은 응답의 `Contents`를 클라이언트 측에서 필터링합니다.
</Note>