Metadata-Version: 2.4
Name: apiyi-sdk
Version: 0.2.0
Summary: Python SDK for APIYi image & video APIs (GPT-Image-2, Nano Banana, VEO 3.1, Seedance 2.0, icover asset library)
Project-URL: Homepage, https://docs.apiyi.com
Project-URL: Documentation, https://docs.apiyi.com
Project-URL: Repository, https://github.com/suix-maker/apiyi_sdk
Project-URL: Issues, https://github.com/suix-maker/apiyi_sdk/issues
Project-URL: Changelog, https://github.com/suix-maker/apiyi_sdk/blob/main/CHANGELOG.md
Author: apiyi-sdk contributors
License: MIT
License-File: LICENSE
Keywords: apiyi,gpt-image,image-generation,nano-banana,seedance,veo,video-generation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# apiyi-sdk

Python SDK for [APIYi](https://docs.apiyi.com) image & video generation APIs.

## Supported APIs

### Images

| Resource | Model | Text-to-image | Image edit |
|----------|-------|---------------|------------|
| `client.gpt_image_all` | `gpt-image-2-all` | ✅ | ✅ |
| `client.gpt_image_vip` | `gpt-image-2-vip` | ✅ | ✅ |
| `client.nano_banana_2` | `gemini-3.1-flash-image-preview` | ✅ | ✅ |
| `client.nano_banana_lite` | `gemini-3.1-flash-lite-image` | ✅ | ✅ |

### Videos

| Resource | Capabilities |
|----------|--------------|
| `client.veo` | VEO 3.1 文生视频 / 图生视频（异步：创建 → 轮询 → 下载） |
| `client.seedance2` | Seedance 2.0 文生视频 / 首尾帧 / 多模态参考 |
| `client.asset_library` | icover 素材库（上传 → 入库 → `asset://` ID） |
| `client.asset_reference` | 端到端：本地图片入库 + 素材引用生视频 |

## Install

```bash
# 本地开发
pip install -e "./apiyi_sdk[dev]"

# PyPI（发布后）
pip install apiyi-sdk

# Git
pip install "apiyi-sdk @ git+https://github.com/suix-maker/apiyi_sdk.git@v0.2.0"
```

## Quick start

```python
import os
from apiyi_sdk import ApiyiClient, ImageInput

client = ApiyiClient(
    api_key=os.environ["APIYI_API_KEY"],
    seedance_api_key=os.environ.get("APIYI_SEEDANCE2_API_KEY"),
    asset_library_api_key=os.environ.get("ICOVER_ASSET_LIBRARY_KEY"),
)

# VEO 文生视频（seconds 必须是字符串 "4" / "6" / "8"）
task = client.veo.create_text_to_video(
    "黄昏海边的灯塔，镜头缓慢推进，海浪声",
    seconds="8",
    resolution="720p",
)
task = client.veo.wait_for_completion(task.task_id)
mp4_bytes = client.veo.download_content(task.task_id)

# VEO 图生视频（multipart，字段 input_reference，仅 1 张图）
task = client.veo.create_image_to_video(
    "镜头从灯塔基座缓慢上升",
    ImageInput.from_path("lighthouse.png"),
    seconds="8",
)

# Seedance 2.0 文生视频
result = client.seedance2.generate_text_to_video(
    "海浪拍打礁石，夕阳金色海面",
    duration=5,
    generate_audio=False,
)

# 素材引用全流程（需素材库 KEY + SeeDance2 KEY）
result = client.require_asset_reference().run(
    "portrait.jpg",
    "图片1中的人物正面微笑，镜头缓慢推近，自然光",
)
print(result.video.video_url)
```

## API Keys

SDK **不包含任何密钥**，运行时由调用方传入。

| 用途 | 参数 | 环境变量 | 说明 |
|------|------|----------|------|
| 生图 / VEO | `api_key` | `APIYI_API_KEY` | API易控制台令牌 |
| Seedance 2.0 | `seedance_api_key` | `APIYI_SEEDANCE2_API_KEY` | 须勾选 `SeeDance2` 分组；未传则回退 `api_key` |
| 素材库 | `asset_library_api_key` | `ICOVER_ASSET_LIBRARY_KEY` | icover.ai「设置 → 素材库 KEY」，**独立 sk，不可与 SeeDance2 混用** |

未配置 `asset_library_api_key` 时，`client.asset_library` 与 `client.asset_reference` 为 `None`。

## Development

```bash
cd apiyi_sdk
pip install -e ".[dev]"
pytest
python -m build
```

## Publish

```bash
python -m build
twine upload --repository testpypi dist/*   # 先试装
twine upload dist/*                         # 正式 PyPI
```

## Docs

- [GPT-Image-2 all 文生图](https://docs.apiyi.com/api-capabilities/gpt-image-2-all/text-to-image)
- [VEO 3.1 文生视频](https://docs.apiyi.com/api-capabilities/veo-3-1-official/text-to-video)
- [VEO 3.1 图生视频](https://docs.apiyi.com/api-capabilities/veo-3-1-official/image-to-video)
- [Seedance 2.0 视频生成](https://docs.apiyi.com/api-capabilities/seedance2/video-generation)
- [Seedance 2.0 素材库](https://docs.apiyi.com/api-capabilities/seedance2/asset-library)
- [素材引用实战](https://docs.apiyi.com/api-capabilities/seedance2/asset-reference)

## License

MIT — see [LICENSE](LICENSE).
