Metadata-Version: 2.4
Name: huace-aigc-oss-proxy-client
Version: 0.1.7
Summary: 华策 AIGC OSS Proxy Client - 统一 RustFS / 阿里云 OSS / 七牛云上传，支持内网/公网默认上传网络
Author-email: Huace <support@huace.com>
License: MIT
Project-URL: Homepage, https://github.com/huace/huace-aigc-oss-proxy-client
Project-URL: Repository, https://github.com/huace/huace-aigc-oss-proxy-client
Keywords: aigc,oss,huace,sdk,rustfs,aliyun,s3
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: aliyun
Requires-Dist: oss2>=2.18.0; extra == "aliyun"
Provides-Extra: rustfs
Requires-Dist: boto3>=1.34.0; extra == "rustfs"
Provides-Extra: qiniu
Requires-Dist: qiniu>=7.12.0; extra == "qiniu"
Requires-Dist: requests>=2.20.0; extra == "qiniu"
Provides-Extra: all
Requires-Dist: oss2>=2.18.0; extra == "all"
Requires-Dist: boto3>=1.34.0; extra == "all"
Requires-Dist: qiniu>=7.12.0; extra == "all"
Requires-Dist: requests>=2.20.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-env>=1.0.0; extra == "dev"
Requires-Dist: moto[s3]>=5.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"

# AIGC OSS Proxy Python SDK

[![Python Version](https://img.shields.io/pypi/pyversions/huace-aigc-oss-proxy-client.svg)](https://pypi.org/project/huace-aigc-oss-proxy-client/)

华策 AIGC 插件对象存储上传 SDK，支持内网 RustFS 与公网（阿里云 OSS / 七牛云）。

**Python 版本**：`>= 3.10`

## 安装

```bash
# 全量（RustFS + 阿里云 + 七牛）
pip install huace-aigc-oss-proxy-client[all]

# 按需安装
pip install huace-aigc-oss-proxy-client[aliyun]   # 仅阿里云
pip install huace-aigc-oss-proxy-client[rustfs]   # 仅 RustFS
pip install huace-aigc-oss-proxy-client[qiniu]    # 仅七牛
```

## 快速开始

### 1. 配置环境变量

复制 [env.example](./env.example) 为 `.env`，填入 AK/SK、Bucket 等。变量名统一前缀 `HUACE_AIGC_`。

```bash
cp env.example .env
```

### 2. 上传文件

```python
from huace_aigc_oss import OssProxy

proxy = OssProxy.from_env()

# 上传到内网
result = proxy.upload("/tmp/output.wav", "output.wav", route="local")
print(result.url)   # 内网访问地址
print(result.key)   # 对象 key

# 上传到公网
result = proxy.upload("/tmp/output.wav", "output.wav", route="public")
print(result.url)   # 公网访问地址
```

**参数说明**

| 参数 | 说明 |
|------|------|
| 第 1 个参数 | 本地文件路径 |
| `download_name` | 下载时显示的文件名（必填） |
| `route` | `local`（内网）或 `public`（公网）；可省略，见下方环境变量 |

省略 `route` 时，使用环境变量 `HUACE_AIGC_OSS_DEFAULT_UPLOAD_NETWORK` 的值。

## 内网转公网

将内网 RustFS 链接转为阿里云公网链接；若传入的已是公网链接，则原样返回。

```python
from huace_aigc_oss import OssProxy

proxy = OssProxy.from_env()

public_url = proxy.local_to_public_url(
    "http://oss.aigc-transdubbing.huacemedia.com:9000/huace-shortmovie/tmp/abc.mp4"
)
print(public_url)
```

**前提**：`HUACE_AIGC_OSS_ALIYUN_ENABLED=true`，且阿里云凭证已配置。

## 环境变量

完整模板见 [env.example](./env.example)。按用途分组如下。

### 上传网络

| 变量 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `HUACE_AIGC_OSS_DEFAULT_UPLOAD_NETWORK` | 与代码 `route` 至少填一处 | 无 | `local`（内网）或 `public`（公网） |

`route=public` 时，公网后端由以下变量决定（无需单独指定 provider）：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `HUACE_AIGC_OSS_ALIYUN_ENABLED` | `true` | 启用阿里云 |
| `HUACE_AIGC_OSS_QINIU_ENABLED` | `false` | 启用七牛 |

二者均启用时优先阿里云；均未启用时公网上传报错。

**配置示例**

```bash
# 内网 Worker
HUACE_AIGC_OSS_DEFAULT_UPLOAD_NETWORK=local

# 公网（阿里云）
HUACE_AIGC_OSS_DEFAULT_UPLOAD_NETWORK=public
HUACE_AIGC_OSS_ALIYUN_ENABLED=true
HUACE_AIGC_OSS_QINIU_ENABLED=false

# 公网（七牛）
HUACE_AIGC_OSS_DEFAULT_UPLOAD_NETWORK=public
HUACE_AIGC_OSS_ALIYUN_ENABLED=false
HUACE_AIGC_OSS_QINIU_ENABLED=true
```

### RustFS（内网）

| 变量 | 必填 | 默认值 |
|------|------|--------|
| `HUACE_AIGC_OSS_RUSTFS_ACCESS_KEY` | 是 | — |
| `HUACE_AIGC_OSS_RUSTFS_SECRET_KEY` | 是 | — |
| `HUACE_AIGC_OSS_RUSTFS_BUCKET` | 是 | — |
| `HUACE_AIGC_OSS_RUSTFS_KEY_PREFIX` | 否 | `tmp` |

### 阿里云 OSS（公网）

| 变量 | 必填 | 默认值 |
|------|------|--------|
| `HUACE_AIGC_OSS_ALIYUN_ENABLED` | 否 | `true` |
| `HUACE_AIGC_OSS_ALIYUN_ACCESS_KEY_ID` | 启用时必填 | — |
| `HUACE_AIGC_OSS_ALIYUN_ACCESS_KEY_SECRET` | 启用时必填 | — |
| `HUACE_AIGC_OSS_ALIYUN_BUCKET` | 启用时必填 | — |
| `HUACE_AIGC_OSS_ALIYUN_KEY_PREFIX` | 否 | `tmp` |

### 七牛云（公网，可选）

| 变量 | 必填 | 默认值 |
|------|------|--------|
| `HUACE_AIGC_OSS_QINIU_ENABLED` | 否 | `false` |
| `HUACE_AIGC_OSS_QINIU_ACCESS_KEY` | 启用时必填 | — |
| `HUACE_AIGC_OSS_QINIU_SECRET_KEY` | 启用时必填 | — |
| `HUACE_AIGC_OSS_QINIU_BUCKET` | 启用时必填 | — |
| `HUACE_AIGC_OSS_QINIU_DOMAIN` | 启用时必填 | — |
| `HUACE_AIGC_OSS_QINIU_KEY_PREFIX` | 否 | `tmp` |

## Docker 部署

容器内需能解析内网 OSS 域名，添加 `extra_hosts`：

```yaml
extra_hosts:
  - "oss.aigc-transdubbing.huacemedia.com:192.168.1.18"
```

## 示例项目

更多命令行示例见 [example/](./example/) 目录：

```bash
cd example
cp .env.example .env   # 填入凭证
pip install -r requirements.txt
python upload_file.py "assert/2.mp4" "2.mp4" --route public
```
