p0aiapi 0.1.0__tar.gz

p0aiapi-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: Test and build
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ['3.10', '3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e '.[dev]'
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: pytest
+      - run: python -m build
+      - run: python -m twine check dist/*

p0aiapi-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish package
+on:
+  workflow_dispatch:
+    inputs:
+      repository:
+        description: Package index
+        required: true
+        default: testpypi
+        type: choice
+        options: [testpypi, pypi]
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - run: python -m pip install -e '.[dev]'
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: pytest
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.repository }}
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - name: Publish to TestPyPI
+        if: inputs.repository == 'testpypi'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+      - name: Publish to PyPI
+        if: inputs.repository == 'pypi'
+        uses: pypa/gh-action-pypi-publish@release/v1

p0aiapi-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+.tmp/
+.idea/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.env
+openapi.local.json

p0aiapi-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.5
+Name: p0aiapi
+Version: 0.1.0
+Summary: Sync and async Python client for the P0 AI API, with OpenAPI-driven calls
+Keywords: aiapi,openapi,p0,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=0.24; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# p0aiapi
+
+P0 API 的 Python SDK，支持 Python 3.10+、同步 / asyncio 调用、任务轮询、音色上传、SSE 和 OpenAPI JSON 动态调用。运行时仅依赖 `httpx`。
+
+发行包和导入名称均为 `p0aiapi`，版本 `0.1.0`。默认 API 地址为 **`https://p0-api.inaiai.com`**。
+
+下面的服务接口均见于 [YApi 项目 8](https://yapi.inaiai.com/project/8/interface/api)。包内接口配置结合 YApi 与本地 backend 源码维护；接口是否可用仍取决于实际部署版本。SDK 不会把文档路径自动替换成其他接口。
+
+## 安装与快速开始
+
+```bash
+python -m pip install p0aiapi
+export P0_API_KEY='你的 API key'
+```
+
+本地开发可使用 `python -m pip install -e .`。
+
+```python
+from p0aiapi import Client
+
+with Client() as client:
+    task = client.audio.generate("你好，欢迎使用 P0 API。")
+    result = client.wait_for_task(task["task_id"], timeout=600, poll_interval=10)
+    print(result.get("out_data"))
+```
+
+需要连接其他部署时，设置 `P0_API_BASE_URL`，或传入 `Client(base_url="https://your-api.example.com", api_key="...")`。显式参数优先于环境变量，未设置地址时使用 `https://p0-api.inaiai.com`。地址填写服务根地址；反向代理的路径前缀会被保留。
+
+认证使用 **`apikey` 请求头**。`api_key=` / `P0_API_KEY` 设置该请求头；可选的 `token=` / `P0_API_TOKEN` 额外发送 `Authorization: Bearer ...`，不替代 apikey。SDK 不内置密钥，初始化不会访问服务器。使用 `with` 管理连接，或在结束时调用 `close()`。
+
+## 异步调用
+
+```python
+import asyncio
+from p0aiapi import AsyncClient
+
+
+async def main():
+    async with AsyncClient() as client:
+        task = await client.audio.generate("你好，这是异步语音生成示例。")
+        result = await client.wait_for_task(task["task_id"], timeout=600, poll_interval=10)
+        print(result)
+
+
+asyncio.run(main())
+```
+
+异步客户端在同一个 asyncio 事件循环中复用，结束时使用 `async with` 或 `await client.aclose()`。
+
+## 常用接口
+
+同步和异步客户端的方法同名；异步请求方法需要 `await`。
+
+| 方法 | 用途 |
+| --- | --- |
+| `client.images.generate(prompt, **fields)` | 文生图 |
+| `client.novels.generate(description, **fields)` | 提交小说生成任务 |
+| `client.novels.continue_from(file_url, **fields)` | 从公网 TXT / Markdown 文件续写 |
+| `client.audio.list_voices()` | TTS v1 音色列表 |
+| `client.audio.generate(text, **fields)` | TTS v1 语音生成 |
+| `client.audio.upload_voice(spk_id, prompt_text, path)` | 上传音色样本及对应文本 |
+| `client.tts.list_speakers()` | TTS v2 音色列表 |
+| `client.tts.generate(text, spk_id, **fields)` | TTS v2 语音生成 |
+| `client.tasks.get(task_id)` | 查询任务记录 |
+| `client.tasks.batch([task_id, ...])` | 批量查询任务记录，发送裸 JSON 数组 |
+| `client.tasks.events([task_id, ...])` | 逐条读取 SSE 任务事件 |
+| `client.wait_for_task(task_id, timeout=600)` | 本地轮询，等待任务结束 |
+
+生成方法使用后端要求的表单编码。`**fields` 透传可选参数并省略 `None`，例如具体接口支持的 `task_id`、`bid`、`app_id`、`notify_url`。实际字段和默认值以对应接口为准，响应保留原始结构及新增字段。
+
+音色上传使用 multipart，SDK 会关闭自己打开的文件；直接调用 `request(files=...)` 时由调用方管理文件句柄。
+
+```python
+with Client() as client:
+    voice = client.audio.upload_voice("my-voice", "音频中的原文", "sample.wav")
+    print(voice)
+```
+
+任务查询使用 `/api/public/task`；同一 `task_id` 存在多条记录时，返回记录由服务端决定。批量查询使用 YApi [3469](https://yapi.inaiai.com/project/8/interface/api/3469) 的 `/api/public/task/details`：传入非空 `task_id` 列表，成功响应直接返回任务对象数组。未命中的 ID 被省略，结果顺序可能与输入不同，同一 ID 可能返回多条记录；所有 ID 均未命中时返回 404。请按 `task_id` 关联结果，不能用内部 `uuid` 或业务 `bid` 替代。
+
+## OpenAPI 接口配置
+
+### 使用包内配置
+
+`load_catalog()` 离线加载随包安装的接口配置，使用 `yapi_接口ID` 作为 operationId。配置只包含本版本支持的 YApi 接口，请求参数按本地 backend 签名校正，不包含文档中的密钥和示例值。
+
+```python
+from p0aiapi import Client, load_catalog
+
+with Client(openapi=load_catalog()) as client:
+    voices = client.call("yapi_2526")
+    tasks = client.call_endpoint("POST", "/api/public/task/details", json=["task-1", "task-2"])
+    print(voices, tasks)
+```
+
+```bash
+p0aiapi operations
+p0aiapi export-catalog --output openapi.catalog.json
+```
+
+`call_endpoint()` 通过方法和路径模板定位已加载的操作。动态调用显式区分 `path_params`、`params`（query）、`headers`、`cookies`、`json`、`data`（form）和 `files`。表单接口使用 `data`，不能改用 `json`。动态调用共用客户端认证、超时和错误处理。
+
+### 下载部署配置
+
+```bash
+p0aiapi fetch-schema --output openapi.json
+p0aiapi operations openapi.json
+```
+
+CLI 同样使用默认 API 地址和 `P0_API_BASE_URL` / `P0_API_KEY` / `P0_API_TOKEN`。文档路径默认 `/openapi.json`，可通过 `--path` 指定。下载检查版本和操作目录结构后原子替换文件，失败保留原文件。
+
+```python
+from p0aiapi import Client
+
+with Client(openapi="openapi.json") as client:
+    print(list(client.schema.operations))
+```
+
+也可传入字典或 `OpenAPISchema`。`client.load_openapi("new.json")` 从本地更新；`client.refresh_openapi()` / `await client.refresh_openapi()` 显式从当前部署下载。加载或刷新会替换当前配置，验证失败时保留原配置；部署文档可能隐藏部分路由，不自动与包内目录合并。
+
+### 升级前比较
+
+```bash
+p0aiapi fetch-schema --output openapi.next.json
+p0aiapi diff openapi.json openapi.next.json --fail-on-change
+```
+
+输出 `added` / `removed` / `changed` operationId 列表，包含引用模型变化。`--fail-on-change` 遇到任何差异返回退出码 2，但不自动判定业务兼容性。生产项目建议把快照与代码一起版本控制，测试后升级。
+
+支持 OpenAPI 3.0 / 3.1 JSON、本地 `$ref`、JSON / URL-encoded / multipart 请求、简单路径参数和普通 query 数组。不支持 YAML、Swagger 2.0 或 deepObject 等复杂序列化；不做完整 JSON Schema 校验，也不生成接口专属类型。便利方法不依赖 OpenAPI 配置，响应不按文档强制转换类型。
+
+`request_raw()` 返回完整读取的 `httpx.Response`；`request()` 根据响应类型返回 JSON、文本、字节或 `None`。API 请求地址由客户端的 `base_url` 决定，schema 的 `servers` 不覆盖它。
+
+## SSE 任务事件
+
+使用 `tasks.events()`、`stream_events()` 或 `stream_call()` 增量读取事件。普通 `request()` / `call()` 会等待响应结束。流式读取不自动重试或重连，`timeout=60` 可设置读取空闲超时。
+
+```python
+from contextlib import closing
+from p0aiapi import Client
+
+with Client() as client:
+    with closing(client.tasks.events(["task-1", "task-2"], timeout=60)) as events:
+        for event in events:
+            print(event.event, event.data)
+```
+
+异步版本返回异步迭代器，创建时不加 `await`：
+
+```python
+from contextlib import aclosing
+from p0aiapi import AsyncClient
+
+
+async def watch():
+    async with AsyncClient() as client:
+        async with aclosing(client.tasks.events(["task-1"])) as events:
+            async for event in events:
+                print(event.data)
+```
+
+迭代结束、异常或显式 `close()` / `aclose()` 会释放连接；提前退出循环时使用上面的上下文管理器。`ServerSentEvent` 保留原始 `data`、事件名称、id 和 retry；仅在数据确实为 JSON 时调用 `event.json()`。服务端事件名称可能与任务终态不同，最终结果使用任务 `status` 判断或调用 `wait_for_task()`。
+
+## 错误、重试和任务状态
+
+```python
+from p0aiapi import APIError, Client, TaskFailedError, TaskTimeoutError
+
+with Client() as client:
+    try:
+        task = client.audio.generate("你好，世界。")
+        result = client.wait_for_task(task["task_id"], timeout=600, poll_interval=10)
+    except APIError as exc:
+        print(exc.status_code)
+        if isinstance(exc.body, dict) and exc.body.get("submission_uncertain"):
+            print("任务可能已入队，请先查询：", exc.body.get("task_id"))
+    except TaskFailedError as exc:
+        print(exc.task.get("error"))
+    except TaskTimeoutError as exc:
+        print("停止本地等待，后端任务仍在执行", exc.last_task)
+```
+
+- HTTP 错误：`AuthenticationError`（401/403）、`NotFoundError`（404）、`ValidationError`（422）、`RateLimitError`（429）、`ServerError`（5xx）均继承 `APIError`，保留 `.body`、`.response`、`.request_id`。默认异常文字不回显凭据或响应内容。
+- 连接及 HTTP 超时为 `TransportError`；坏 JSON、解压失败或不适用的响应为 `P0ResponseError`。这些错误及任务错误继承 `P0Error`。本地配置错误和 `SchemaError` 继承 `ValueError`。
+- 无请求体的 GET/HEAD/OPTIONS 默认最多重试 2 次，覆盖连接故障和 408/429/500/502/503/504；读取 `Retry-After` 并退避，单次最多等待 30 秒。POST 等写请求不自动重试。若返回 `submission_uncertain=true`，应先查询任务，避免重复提交。
+- 状态 `0` 等待、`1` 处理、`3` 水印处理中，继续等待；`2` 成功；`-1` 抛出 `TaskFailedError`，或通过 `raise_on_failure=False` 返回失败记录。数字字符串也受支持，未知状态继续等待至超时。
+- 轮询在总预算内处理临时连接故障及上述可重试 HTTP 状态；404 和认证错误立即抛出。任务查询可能缓存约 10 秒，建议 `poll_interval=10`。超时只停止本地等待，不取消远端任务。
+- 同步 HTTP 超时按网络阶段计算，正在执行的请求可能超过轮询截止时间；异步等待使用总 deadline，可被调用方取消。
+- API 路径必须为 `/...`；不接受外部 URL，也不自动跟随跳转。下载外部结果请使用独立的 HTTP 客户端。
+
+## 开发和发布
+
+```bash
+python -m pip install -e '.[dev]'
+pytest
+ruff check .
+ruff format --check .
+python -m build
+python -m twine check dist/p0aiapi-0.1.0-py3-none-any.whl dist/p0aiapi-0.1.0.tar.gz
+```
+
+测试使用模拟 HTTP 验证请求、响应、任务状态和错误处理，不提交真实生成任务。离线演示：`python examples/offline_demo.py`。
+
+[发布步骤](docs/publishing.md) · [架构及接口维护](docs/design.md)。GitHub Actions 包含测试矩阵和手动 TestPyPI / PyPI 发布流程。

p0aiapi-0.1.0/README.md

@@ -0,0 +1,204 @@
+# p0aiapi
+
+P0 API 的 Python SDK，支持 Python 3.10+、同步 / asyncio 调用、任务轮询、音色上传、SSE 和 OpenAPI JSON 动态调用。运行时仅依赖 `httpx`。
+
+发行包和导入名称均为 `p0aiapi`，版本 `0.1.0`。默认 API 地址为 **`https://p0-api.inaiai.com`**。
+
+下面的服务接口均见于 [YApi 项目 8](https://yapi.inaiai.com/project/8/interface/api)。包内接口配置结合 YApi 与本地 backend 源码维护；接口是否可用仍取决于实际部署版本。SDK 不会把文档路径自动替换成其他接口。
+
+## 安装与快速开始
+
+```bash
+python -m pip install p0aiapi
+export P0_API_KEY='你的 API key'
+```
+
+本地开发可使用 `python -m pip install -e .`。
+
+```python
+from p0aiapi import Client
+
+with Client() as client:
+    task = client.audio.generate("你好，欢迎使用 P0 API。")
+    result = client.wait_for_task(task["task_id"], timeout=600, poll_interval=10)
+    print(result.get("out_data"))
+```
+
+需要连接其他部署时，设置 `P0_API_BASE_URL`，或传入 `Client(base_url="https://your-api.example.com", api_key="...")`。显式参数优先于环境变量，未设置地址时使用 `https://p0-api.inaiai.com`。地址填写服务根地址；反向代理的路径前缀会被保留。
+
+认证使用 **`apikey` 请求头**。`api_key=` / `P0_API_KEY` 设置该请求头；可选的 `token=` / `P0_API_TOKEN` 额外发送 `Authorization: Bearer ...`，不替代 apikey。SDK 不内置密钥，初始化不会访问服务器。使用 `with` 管理连接，或在结束时调用 `close()`。
+
+## 异步调用
+
+```python
+import asyncio
+from p0aiapi import AsyncClient
+
+
+async def main():
+    async with AsyncClient() as client:
+        task = await client.audio.generate("你好，这是异步语音生成示例。")
+        result = await client.wait_for_task(task["task_id"], timeout=600, poll_interval=10)
+        print(result)
+
+
+asyncio.run(main())
+```
+
+异步客户端在同一个 asyncio 事件循环中复用，结束时使用 `async with` 或 `await client.aclose()`。
+
+## 常用接口
+
+同步和异步客户端的方法同名；异步请求方法需要 `await`。
+
+| 方法 | 用途 |
+| --- | --- |
+| `client.images.generate(prompt, **fields)` | 文生图 |
+| `client.novels.generate(description, **fields)` | 提交小说生成任务 |
+| `client.novels.continue_from(file_url, **fields)` | 从公网 TXT / Markdown 文件续写 |
+| `client.audio.list_voices()` | TTS v1 音色列表 |
+| `client.audio.generate(text, **fields)` | TTS v1 语音生成 |
+| `client.audio.upload_voice(spk_id, prompt_text, path)` | 上传音色样本及对应文本 |
+| `client.tts.list_speakers()` | TTS v2 音色列表 |
+| `client.tts.generate(text, spk_id, **fields)` | TTS v2 语音生成 |
+| `client.tasks.get(task_id)` | 查询任务记录 |
+| `client.tasks.batch([task_id, ...])` | 批量查询任务记录，发送裸 JSON 数组 |
+| `client.tasks.events([task_id, ...])` | 逐条读取 SSE 任务事件 |
+| `client.wait_for_task(task_id, timeout=600)` | 本地轮询，等待任务结束 |
+
+生成方法使用后端要求的表单编码。`**fields` 透传可选参数并省略 `None`，例如具体接口支持的 `task_id`、`bid`、`app_id`、`notify_url`。实际字段和默认值以对应接口为准，响应保留原始结构及新增字段。
+
+音色上传使用 multipart，SDK 会关闭自己打开的文件；直接调用 `request(files=...)` 时由调用方管理文件句柄。
+
+```python
+with Client() as client:
+    voice = client.audio.upload_voice("my-voice", "音频中的原文", "sample.wav")
+    print(voice)
+```
+
+任务查询使用 `/api/public/task`；同一 `task_id` 存在多条记录时，返回记录由服务端决定。批量查询使用 YApi [3469](https://yapi.inaiai.com/project/8/interface/api/3469) 的 `/api/public/task/details`：传入非空 `task_id` 列表，成功响应直接返回任务对象数组。未命中的 ID 被省略，结果顺序可能与输入不同，同一 ID 可能返回多条记录；所有 ID 均未命中时返回 404。请按 `task_id` 关联结果，不能用内部 `uuid` 或业务 `bid` 替代。
+
+## OpenAPI 接口配置
+
+### 使用包内配置
+
+`load_catalog()` 离线加载随包安装的接口配置，使用 `yapi_接口ID` 作为 operationId。配置只包含本版本支持的 YApi 接口，请求参数按本地 backend 签名校正，不包含文档中的密钥和示例值。
+
+```python
+from p0aiapi import Client, load_catalog
+
+with Client(openapi=load_catalog()) as client:
+    voices = client.call("yapi_2526")
+    tasks = client.call_endpoint("POST", "/api/public/task/details", json=["task-1", "task-2"])
+    print(voices, tasks)
+```
+
+```bash
+p0aiapi operations
+p0aiapi export-catalog --output openapi.catalog.json
+```
+
+`call_endpoint()` 通过方法和路径模板定位已加载的操作。动态调用显式区分 `path_params`、`params`（query）、`headers`、`cookies`、`json`、`data`（form）和 `files`。表单接口使用 `data`，不能改用 `json`。动态调用共用客户端认证、超时和错误处理。
+
+### 下载部署配置
+
+```bash
+p0aiapi fetch-schema --output openapi.json
+p0aiapi operations openapi.json
+```
+
+CLI 同样使用默认 API 地址和 `P0_API_BASE_URL` / `P0_API_KEY` / `P0_API_TOKEN`。文档路径默认 `/openapi.json`，可通过 `--path` 指定。下载检查版本和操作目录结构后原子替换文件，失败保留原文件。
+
+```python
+from p0aiapi import Client
+
+with Client(openapi="openapi.json") as client:
+    print(list(client.schema.operations))
+```
+
+也可传入字典或 `OpenAPISchema`。`client.load_openapi("new.json")` 从本地更新；`client.refresh_openapi()` / `await client.refresh_openapi()` 显式从当前部署下载。加载或刷新会替换当前配置，验证失败时保留原配置；部署文档可能隐藏部分路由，不自动与包内目录合并。
+
+### 升级前比较
+
+```bash
+p0aiapi fetch-schema --output openapi.next.json
+p0aiapi diff openapi.json openapi.next.json --fail-on-change
+```
+
+输出 `added` / `removed` / `changed` operationId 列表，包含引用模型变化。`--fail-on-change` 遇到任何差异返回退出码 2，但不自动判定业务兼容性。生产项目建议把快照与代码一起版本控制，测试后升级。
+
+支持 OpenAPI 3.0 / 3.1 JSON、本地 `$ref`、JSON / URL-encoded / multipart 请求、简单路径参数和普通 query 数组。不支持 YAML、Swagger 2.0 或 deepObject 等复杂序列化；不做完整 JSON Schema 校验，也不生成接口专属类型。便利方法不依赖 OpenAPI 配置，响应不按文档强制转换类型。
+
+`request_raw()` 返回完整读取的 `httpx.Response`；`request()` 根据响应类型返回 JSON、文本、字节或 `None`。API 请求地址由客户端的 `base_url` 决定，schema 的 `servers` 不覆盖它。
+
+## SSE 任务事件
+
+使用 `tasks.events()`、`stream_events()` 或 `stream_call()` 增量读取事件。普通 `request()` / `call()` 会等待响应结束。流式读取不自动重试或重连，`timeout=60` 可设置读取空闲超时。
+
+```python
+from contextlib import closing
+from p0aiapi import Client
+
+with Client() as client:
+    with closing(client.tasks.events(["task-1", "task-2"], timeout=60)) as events:
+        for event in events:
+            print(event.event, event.data)
+```
+
+异步版本返回异步迭代器，创建时不加 `await`：
+
+```python
+from contextlib import aclosing
+from p0aiapi import AsyncClient
+
+
+async def watch():
+    async with AsyncClient() as client:
+        async with aclosing(client.tasks.events(["task-1"])) as events:
+            async for event in events:
+                print(event.data)
+```
+
+迭代结束、异常或显式 `close()` / `aclose()` 会释放连接；提前退出循环时使用上面的上下文管理器。`ServerSentEvent` 保留原始 `data`、事件名称、id 和 retry；仅在数据确实为 JSON 时调用 `event.json()`。服务端事件名称可能与任务终态不同，最终结果使用任务 `status` 判断或调用 `wait_for_task()`。
+
+## 错误、重试和任务状态
+
+```python
+from p0aiapi import APIError, Client, TaskFailedError, TaskTimeoutError
+
+with Client() as client:
+    try:
+        task = client.audio.generate("你好，世界。")
+        result = client.wait_for_task(task["task_id"], timeout=600, poll_interval=10)
+    except APIError as exc:
+        print(exc.status_code)
+        if isinstance(exc.body, dict) and exc.body.get("submission_uncertain"):
+            print("任务可能已入队，请先查询：", exc.body.get("task_id"))
+    except TaskFailedError as exc:
+        print(exc.task.get("error"))
+    except TaskTimeoutError as exc:
+        print("停止本地等待，后端任务仍在执行", exc.last_task)
+```
+
+- HTTP 错误：`AuthenticationError`（401/403）、`NotFoundError`（404）、`ValidationError`（422）、`RateLimitError`（429）、`ServerError`（5xx）均继承 `APIError`，保留 `.body`、`.response`、`.request_id`。默认异常文字不回显凭据或响应内容。
+- 连接及 HTTP 超时为 `TransportError`；坏 JSON、解压失败或不适用的响应为 `P0ResponseError`。这些错误及任务错误继承 `P0Error`。本地配置错误和 `SchemaError` 继承 `ValueError`。
+- 无请求体的 GET/HEAD/OPTIONS 默认最多重试 2 次，覆盖连接故障和 408/429/500/502/503/504；读取 `Retry-After` 并退避，单次最多等待 30 秒。POST 等写请求不自动重试。若返回 `submission_uncertain=true`，应先查询任务，避免重复提交。
+- 状态 `0` 等待、`1` 处理、`3` 水印处理中，继续等待；`2` 成功；`-1` 抛出 `TaskFailedError`，或通过 `raise_on_failure=False` 返回失败记录。数字字符串也受支持，未知状态继续等待至超时。
+- 轮询在总预算内处理临时连接故障及上述可重试 HTTP 状态；404 和认证错误立即抛出。任务查询可能缓存约 10 秒，建议 `poll_interval=10`。超时只停止本地等待，不取消远端任务。
+- 同步 HTTP 超时按网络阶段计算，正在执行的请求可能超过轮询截止时间；异步等待使用总 deadline，可被调用方取消。
+- API 路径必须为 `/...`；不接受外部 URL，也不自动跟随跳转。下载外部结果请使用独立的 HTTP 客户端。
+
+## 开发和发布
+
+```bash
+python -m pip install -e '.[dev]'
+pytest
+ruff check .
+ruff format --check .
+python -m build
+python -m twine check dist/p0aiapi-0.1.0-py3-none-any.whl dist/p0aiapi-0.1.0.tar.gz
+```
+
+测试使用模拟 HTTP 验证请求、响应、任务状态和错误处理，不提交真实生成任务。离线演示：`python examples/offline_demo.py`。
+
+[发布步骤](docs/publishing.md) · [架构及接口维护](docs/design.md)。GitHub Actions 包含测试矩阵和手动 TestPyPI / PyPI 发布流程。

p0aiapi-0.1.0/docs/backend-compatibility.md

@@ -0,0 +1,54 @@
+# backend 适配核对（2026-10-08）
+
+本地 `/Users/allenflux/PycharmProjects/backend` 已具备 SDK 所用的主要请求契约，121 个相关离线测试通过。默认域名的线上 OpenAPI 与本地公开契约有明确差异，部署仍需核对或同步；不能据此认定线上已完成全部适配，也不能仅因接口未出现在 OpenAPI 就认定路由不存在。
+
+本次仅读取后端源码并使用内存、AST 提取和 mock 测试，没有修改 backend，没有创建线上生成任务，没有调用真实模型、MQ、数据库或音色服务。线上检查只读取 [默认服务的 OpenAPI](https://p0-api.inaiai.com/openapi.json)（HTTP 200，20 个 paths，`info.title=API`，`info.version=0.0.0`）。
+
+## 本次 SDK 已完成的适配
+
+- `tasks.get()` 和 `wait_for_task()` 使用 `GET /api/public/task`；`tasks.batch()` 使用 `POST /api/public/task/details`，请求体为裸 JSON 字符串数组。同步、异步客户端保持一致。这两个 public 接口同时存在于 YApi、线上公开 schema 和本地后端。
+- public 单任务查询没有按时间选最新记录的保证：它直接调用 `storage.find_one()`。SDK 已移除“总是返回最新任务”的表述。证据：[public 查询](/Users/allenflux/PycharmProjects/backend/src/routers/public.py:654)、[缓存查询实现](/Users/allenflux/PycharmProjects/backend/src/routers/public.py:687)、[存储实现](/Users/allenflux/PycharmProjects/backend/src/storage/storage.py:51)、[批量请求](/Users/allenflux/PycharmProjects/backend/src/routers/public.py:721)。
+- `api_key` 以 `apikey` 请求头发送，匹配[后端鉴权](/Users/allenflux/PycharmProjects/backend/src/middleware/auth.py:173)。只提供 Bearer token 不能替代此后端要求的 `apikey`。
+- 当前 27 个内置 YApi catalog 操作均可对应本地已注册的路由。路由注册证据：[server](/Users/allenflux/PycharmProjects/backend/src/server.py:196)。表单字段、音频 v1 multipart 文件名、批量 JSON 数组、任务 `task_id`/`uuid` 分离均与本地契约吻合。
+
+## 线上部署需要核对的部分
+
+| 接口或能力 | 本地证据 | 线上公开 schema |
+| --- | --- | --- |
+| 图片生成和图生图 | [workflow.py:1622](/Users/allenflux/PycharmProjects/backend/src/routers/workflow.py:1622)、[workflow.py:1742](/Users/allenflux/PycharmProjects/backend/src/routers/workflow.py:1742) | 无 `/api/public/generate/text2image`、`/api/public/generate/image2image`；本地均公开 |
+| TTS v2 生成、音色列表 | [public.py:2736](/Users/allenflux/PycharmProjects/backend/src/routers/public.py:2736)、[public.py:2660](/Users/allenflux/PycharmProjects/backend/src/routers/public.py:2660) | 无 `/api/public/generate/ttsv2`、`/api/public/generate/ttsv2/speakers`；本地均公开 |
+| 小说续写 | [public.py:2363](/Users/allenflux/PycharmProjects/backend/src/routers/public.py:2363) | 无 `/api/public/continue/novel`；本地公开 |
+| 按 UUID 查询任务 | [public.py:673](/Users/allenflux/PycharmProjects/backend/src/routers/public.py:673) | 无 `/api/public/task/uuid`；本地公开 |
+| workflow 健康检查、按业务编号查询等 | [workflow.py:102](/Users/allenflux/PycharmProjects/backend/src/routers/workflow.py:102)、[workflow.py:2187](/Users/allenflux/PycharmProjects/backend/src/routers/workflow.py:2187) | 无任何 `/api/workflow/*` 路径 |
+| 文件上传、下载和分页任务列表 | [utils.py:77](/Users/allenflux/PycharmProjects/backend/src/routers/utils.py:77)、[tasks.py:84](/Users/allenflux/PycharmProjects/backend/src/routers/tasks.py:84) | 本地明确 `include_in_schema=False`；schema 无法确认这些隐藏路由的部署状态 |
+
+字段也有差异：线上 `POST /api/public/generate/audio` 公开的表单字段为 `text`、`spk_id`、`bid`、`app_id`、`notify_url`，没有本地新增的 `task_id`、`hash_key`。线上小说生成 schema 没有本地新增的 `task_id`、`hash_key`、`is_encrypt`。因此，传入自定义 `task_id` 的线上行为仍需确认。对应本地证据：[音频](/Users/allenflux/PycharmProjects/backend/src/routers/workflow.py:3658)、[小说](/Users/allenflux/PycharmProjects/backend/src/routers/public.py:2258)。
+
+SSE 源码把任务字典直接作为事件 `data`，SDK 保留原始字符串，不承诺 `event.json()` 必定成功。证据：[任务 SSE](/Users/allenflux/PycharmProjects/backend/src/routers/public.py:810)。
+
+另一个需修的本地后端问题：TTS v2 把调用方 `api_key` 放入持久化任务，并原样返回。使用虚构密钥和完全 mock 的路由探针已复现；免鉴权任务批量、列表、SSE 查询也未清理此字段。发布对应后端前应过滤响应中的 `api_key`。证据：[TTS v2](/Users/allenflux/PycharmProjects/backend/src/routers/public.py:2772)、[任务序列化](/Users/allenflux/PycharmProjects/backend/src/document.py:43)、[免鉴权查询路径](/Users/allenflux/PycharmProjects/backend/src/middleware/auth.py:23)。
+
+## 离线测试结果与边界
+
+从 backend 目录执行：
+
+```bash
+.venv/bin/python -B -m pytest -q -p no:cacheprovider \
+  tests/test_workflow_task_queries.py \
+  tests/test_public_task_identity.py \
+  tests/test_task_uuid_isolation.py \
+  tests/test_tasks_list.py \
+  tests/test_tts_v1_route_migration_contract.py \
+  tests/test_novel_continuation_api.py \
+  tests/test_novel_generation_limits.py
+```
+
+结果：**108 passed**，1 条 Starlette/AnyIO 弃用警告。覆盖任务查询、批量请求、任务身份、分页、TTS v1 迁移、小说续写与字数限制。
+
+```bash
+.venv/bin/python -B -m pytest -q -p no:cacheprovider tests/test_tts_v1_s3.py
+```
+
+结果：**13 passed**，使用 fake S3 验证音色列表、存储和历史名称适配。
+
+额外尝试 `tests/test_novel_file.py`、`tests/test_novel_file_security.py` 时，本地 backend `.venv` 缺少 `aiohttp`，两个模块无法收集；环境也缺少 `sse_starlette`，未完成完整 SSE 运行验证。未安装依赖、启动完整 server 或验证生产业务执行，因此测试通过范围不包含完整部署和线上生成结果。

p0aiapi-0.1.0/docs/design.md

@@ -0,0 +1,35 @@
+# API 更新与兼容性设计
+
+## 客户端、便利方法与 OpenAPI 快照
+
+客户端负责连接、认证、超时、读取重试、错误和任务等待。`resources.py`、`audio.py` 为常用 YApi 接口提供稳定名称；`openapi.py` 读取部署导出的 JSON，通过 operationId 或 method/path 调用接口；`streaming.py` 增量解析 SSE，并管理流连接的关闭。
+
+默认地址为 `https://p0-api.inaiai.com`，可通过 `P0_API_BASE_URL` 或显式 `base_url` 覆盖。apikey 由 `api_key` / `P0_API_KEY` 设置，可选 bearer token 由 `token` / `P0_API_TOKEN` 设置。SDK 不保存实际密钥。
+
+后端接口仍在变化，部分响应模型与真实数据有类型差异。因此响应保留原始字典和新增字段，当前没有为全部接口生成 Python 类。后续契约稳定后可增加类型层。
+
+OpenAPI 本地加载不访问网络，只有显式 refresh 才下载。schema 的 servers 不参与目的地址选择，外部引用不下载。先检查新文档的版本和操作目录结构，再替换现有目录，失败保留旧版本。正文及响应 schema 不做完整校验，不能把加载成功视为完整契约校验通过。
+
+## 包内接口配置
+
+`schemas/yapi-8.openapi.json` 包含本版本支持的 YApi 接口子集，使用稳定的 `yapi_ID` 命名及本地 backend 的真实参数位置。2026-10-08 通过 YApi 当前分类页面复核接口 ID、方法和路径，新增批量任务查询 `yapi_3469`。其余参数定义沿用 2026-10-01 的脱敏快照并结合源码校正。文档中的密钥及示例值不进入发行包。
+
+任务便利方法与 YApi 的 public 路径一致：单条查询使用 `/api/public/task`，批量查询使用 `/api/public/task/details`。批量查询发送裸 JSON 字符串数组，响应保留 public 接口的原始结构；不借用 workflow 路由的字段清理、结果转换或记录排序行为。单条查询不保证同一 task_id 的最新记录，批量查询可能返回同一 task_id 的多条记录。
+
+可以通过 `load_catalog()` 离线加载内置配置，也可从实际部署下载 `/openapi.json` 并保存自己的快照。加载或刷新会替换当前配置，不自动合并隐藏或删除的接口。内置配置不代表 backend 的全部路由，也不证明线上可用；部署版本及配置决定实际可用接口。SDK 升级不会覆盖用户保存的快照。
+
+本次本地 backend 与线上部署的对照结果见 [后端适配检查](backend-compatibility.md)。SDK 的安装和运行不依赖 sibling backend 目录。
+
+SSE 使用同一认证和部署地址，不自动重连。解析器保留原始数据、事件名称及 id/retry，最终状态判断由普通任务查询及 `wait_for_task()` 负责。
+
+## 后端维护建议
+
+1. 为公开接口显式设置稳定 `operation_id`，避免 FastAPI 自动 ID 随函数重构变化；也可按 method/path 从 SDK 操作目录查找。
+2. 在 OpenAPI security 中声明 apikey，确保希望集成的接口进入部署文档。
+3. 对齐真实响应模型，包括数字 status、历史 fee 类型和 out_data 的多种形态。
+4. 发布时导出 schema 并运行差异检查。当前 diff 能发现参数、响应和引用模型变化，但不判断业务兼容性。
+5. 对删除接口、新增必填字段及改变语义设置版本或弃用周期。
+
+## 验证界限
+
+本地测试通过 HTTPX MockTransport 验证认证头、表单、JSON、multipart、任务状态、重试、取消、响应解压和 OpenAPI 解析，不调用真实模型、队列或数据库。上线前结合实际部署的 schema 与测试账户联调；静态路由检查不能替代生成、文件读取和任务回调的运行验证。