---
title: Tencent COS
description: Configure Tencent Cloud Object Storage (COS) for deployments within the Tencent ecosystem.
createdAt: 2025-11-24T10:06:00+08:00
lastModified: 2025-11-24T22:26:48+08:00
order: 38
---

# Tencent COS Storage

Tencent Cloud COS is fully compatible with the S3 API and now has a dedicated provider inside Afilmory. Using `provider: 'cos'` takes care of bucket/APPID handling and builds the default `cos.<region>.myqcloud.com` endpoint for you.

## Configuration

```typescript
import { defineBuilderConfig } from '@afilmory/builder'

export default defineBuilderConfig(() => ({
  storage: {
    provider: 'cos',
    bucket: process.env.COS_BUCKET!, // include the -APPID suffix, e.g. gallery-1250000000
    region: process.env.COS_REGION || 'ap-shanghai',
    accessKeyId: process.env.COS_SECRET_ID!,
    secretAccessKey: process.env.COS_SECRET_KEY!,
    endpoint: process.env.COS_ENDPOINT, // optional, defaults to https://<bucket>.cos.<region>.myqcloud.com
    prefix: process.env.COS_PREFIX || 'photos/',
    customDomain: process.env.COS_CUSTOM_DOMAIN,
  },
}))
```

## Environment Variables

```bash
# Required
COS_BUCKET=gallery-1250000000
COS_REGION=ap-shanghai
COS_SECRET_ID=AKIDxxxxxxxx
COS_SECRET_KEY=yyyyyyyyyyyy

# Optional
COS_ENDPOINT=https://cos.ap-shanghai.myqcloud.com
COS_PREFIX=photos/
COS_CUSTOM_DOMAIN=https://assets.example.com
```

## COS-specific Considerations

- Buckets MUST include the APPID suffix (`bucketname-125xxxxxxx`).
- Regional endpoints follow the pattern `https://<bucket>.cos.<region>.myqcloud.com`.
- SigV4 service defaults to `s3`, matching Tencent's AWS compatibility layer. Override `sigV4Service` only for private gateways.
- COS supports acceleration and CDN domains; set `customDomain` so generated URLs point to your preferred edge domain.

## Best Practices

- **Use permanent keys** for builder workloads and scope permissions with CAM policies (`name/cos:GetObject`, `cos:PutObject`, etc.).
- **Leverage CLS logs** and bucket inventory to monitor sync health.
- **Combine with SCF or CI** pipelines if you need to trigger builder runs after uploads.

## Troubleshooting

- _403 or 404 errors_: confirm the bucket region matches `COS_REGION` and that the IAM policy allows the requested action.
- _Slow scans_: reduce `downloadConcurrency` or run builder from a Tencent CVM within the same region to minimize latency.
- _Invalid bucket name_: double-check the `-APPID` suffix and that the bucket really exists in the selected region.
