Metadata-Version: 2.5
Name: lingjing-awb
Version: 0.1.0
Summary: Typed synchronous and asynchronous SDK for Lingjing AWB
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.28
Requires-Dist: pydantic<3,>=2.11
Provides-Extra: socks
Requires-Dist: httpx[socks]<1,>=0.28; extra == 'socks'
Description-Content-Type: text/markdown

# Lingjing AWB Python SDK

AWB API 的同步与 asyncio 客户端，要求 Python 3.11+。包名 `lingjing-awb`，导入名 `lingjing_awb`。

```bash
python -m pip install lingjing-awb
```

```python
from lingjing_awb import AwbClient, ImagePromptParams

with AwbClient(access_key="...", project_group_no="...") as client:
    print(client.models.list("IMAGE_CREATE"))
    task = client.images.create(
        model_group_code="...",
        prompt_params=ImagePromptParams(prompt="一只小猫"),
    )
    print(task.task_id)
    result = client.tasks.wait(task.task_id)
    print(result.is_success, result.result_urls)
```

异步客户端为 `AsyncAwbClient`，通过 `async with` 使用，方法加 `await`。支持自定义 HTTPX 客户端，其生命周期由调用方管理。

认证和地址可以从 `LINGJING_AWB_ACCESS_KEY`、`LINGJING_AWB_API_ORIGIN` 读取，显式构造参数优先。默认访问 `https://animeworkbench.lingjingai.cn`，不读取 CLI 状态文件。

业务域包括：`auth`、`account`、`projects`、`credits`、`models`、`uploads`、`images`、`videos`、`audio`、`tasks`、`asset_groups`、`assets`、`subjects`、`voices`。覆盖 lj-awb 的 49 个 API 封装。

- `uploads.upload(path, scene_type=...)` 显式上传本地文件，返回 `backend_path`。
- `images/videos/audio.estimate()` 估价，`create()` 提交任务，`tasks.wait()` 等待终态。
- `images/videos/subjects.create_batch()` 有界并发提交并保留逐项结果。
- `subjects.wait()` 和 `voices.wait()` 等待可用的 `external_id`。
- 标准输入输出使用 Pydantic 模型，动态模型配置和原生分页响应保留 `JsonValue`。
- 不隐式上传、补模型默认参数、改写 prompt、估价或重试。生成会创建真实任务。

运行时错误继承 `AwbError`。HTTP 请求默认超时 20 秒，任务查询、素材注册和 COS PUT 为 60 秒，可由客户端或单次参数覆盖。任务等待默认 300 秒、每 30 秒查询；超时异常保留 ID 与最近状态。

SOCKS 代理可选支持：`python -m pip install 'lingjing-awb[socks]'`。本地源码安装：`python -m pip install .`。仓库开发使用 `uv sync`，运行 `uv run pytest`、`uv run ruff check .`、`uv run mypy`，打包使用 `uv build`。

完整中文文档、接口覆盖表、多语言共享契约样例和 Python 示例随源码仓库提供。测试使用 MockTransport，不访问真实平台。
