nodeimage 0.0.2

NodeImage Python CLI Client

NodeImage

---

重要说明: 本项目是 NodeImage 图片托管服务的第三方实现 Python 客户端，非官方实现。如需官方支持或了解服务详情，请访问 NodeImage 官网。

NodeImage 是一个便捷的 Python 命令行客户端，用于与 NodeImage 图片托管服务进行交互。它提供了简洁的命令行接口和 Python API，让您能够在终端中轻松管理您的图片。

系统要求

NodeImage 需要 Python 3.9 或更高版本。

安装

使用 PyPI 安装：

$ pip install nodeimage

从 GitHub 安装（最新提交）：

$ pip install "git+https://github.com/0x0208v0/nodeimage.git"

指定分支/标签安装：

# 安装 main 分支
$ pip install "git+https://github.com/0x0208v0/nodeimage.git@main"

# 安装指定标签（示例：v0.0.2）
$ pip install "git+https://github.com/0x0208v0/nodeimage.git@v0.0.2"

命令行界面

NodeImage 提供了丰富的命令行界面：

基本命令

# 查看当前版本
$ nodeimage version

# 上传图片
$ nodeimage upload /path/to/image.jpg

# 从URL上传
$ nodeimage upload https://example.com/image.jpg

# 上传多个文件或整个文件夹
$ nodeimage upload img1.jpg img2.png images/

# 列出所有图片（默认只显示ID）
$ nodeimage list

# 列出图片的完整JSON信息
$ nodeimage list -f json

# 导出为CSV或Excel文件
$ nodeimage list -f csv -o images.csv
$ nodeimage list -f xlsx -o images.xlsx

# 下载图片到本地
$ nodeimage download imageid123

# 下载到指定目录
$ nodeimage download imageid123 -o photos/

# 删除图片
$ nodeimage delete imageid123

# 跳过确认直接删除
$ nodeimage delete imageid123 --yes

# 批量操作（支持从文件读取ID列表）
$ nodeimage delete -f image_ids.txt
$ nodeimage download -f image_ids.txt -o downloads/

# 查看调试信息和配置状态
$ nodeimage debug

管道操作

NodeImage 支持通过 Unix 管道进行批量操作，让您能够将 list 命令的输出直接传递给其他命令：

# 下载所有图片到默认目录
$ nodeimage list | nodeimage download --yes

# 下载所有图片到指定目录
$ nodeimage list | nodeimage download --yes -o photos/

# 删除所有图片（危险操作，请谨慎使用）
$ nodeimage list | nodeimage delete --yes

# 结合其他 Unix 工具进行过滤
$ nodeimage list | head -5 | nodeimage download --yes -o recent/
$ nodeimage list | grep "pattern" | nodeimage download --yes
$ nodeimage list | tail -10 | nodeimage delete --yes

# 将图片ID保存到文件，然后批量操作
$ nodeimage list > image_ids.txt
$ cat image_ids.txt | nodeimage download --yes -o backup/

管道操作说明：

• 管道会自动检测，无需额外参数
• 必须使用 --yes 参数跳过确认提示（因为管道占用标准输入，无法进行交互确认）
• 支持与 head、tail、grep 等 Unix 工具组合使用
• 管道输入优先级：命令行参数 > 文件输入 > 管道输入

注意事项：

• 使用管道时如果不加 --yes 参数，程序会显示错误提示并退出
• 删除操作不可撤销，使用管道批量删除时请格外小心

Python API 快速开始

首先导入 NodeImage：

>>> import nodeimage
>>> client = nodeimage.Client("your_api_key_here")

上传本地图片：

>>> result = client.upload_image("/path/to/image.jpg")
>>> print(result)
{'id': 'abc123def456', 'url': 'https://...', 'filename': 'image.jpg'}

从网络URL上传图片：

>>> result = client.upload_image("https://example.com/image.jpg")
>>> print(result)
{'id': 'xyz789uvw012', 'url': 'https://...', 'filename': 'image.jpg'}

列出所有图片：

>>> images = client.get_images()
>>> print(images)
[{'id': 'abc123', 'url': 'https://...', 'filename': 'image1.jpg'}, ...]

删除图片：

>>> result = client.delete_image("abc123def456")
>>> print(result)
{'success': True, 'message': 'Image deleted successfully'}

下载图片：

>>> image_info = client.download_image("abc123def456")
>>> with open(f"downloaded{image_info.ext}", "wb") as f:
...     f.write(image_info.content)
>>> print(f"图片已保存，格式: {image_info.content_type}")

身份认证

环境变量（推荐）

export NODE_IMAGE_API_KEY=your_api_key_here

.env 文件

在项目根目录创建 .env 文件：

NODE_IMAGE_API_KEY=your_api_key_here

命令行参数

nodeimage --api-key your_api_key_here upload image.jpg

Python 代码

from nodeimage import Client

# 直接初始化
client = Client("your_api_key_here")

# 从环境变量创建
client = Client.from_env()

高级用法

自定义配置

from nodeimage import Client

client = Client(
    api_key="your_api_key",
    base_api_url="https://your-custom-api-endpoint.com",
    base_cdn_url="https://your-custom-cdn-endpoint.com",
    timeout=30  # 自定义超时时间（秒）
)

错误处理

from nodeimage import Client

client = Client("your_api_key")

try:
    result = client.upload_image("/path/to/image.jpg")
    print(f"上传成功: {result}")
except Exception as e:
    print(f"上传失败: {e}")

支持的图片格式

NodeImage 支持常见的图片格式：

• JPEG (.jpg, .jpeg)
• PNG (.png)
• GIF (.gif)
• WebP (.webp)
• BMP (.bmp)
• SVG (.svg)

API 参考

Client 类

class Client:
    def __init__(
        self, 
        api_key: str, 
        base_api_url: str = "https://api.nodeimage.com",
        base_cdn_url: str = "https://cdn.nodeimage.com", 
        timeout: float | Timeout | None = 10,
        logger: logging.Logger | None = None
    )
    def upload_image(self, image_path_or_url: str | Path) -> dict
    def get_images(self) -> dict
    def delete_image(self, image_id: str) -> dict
    def download_image(self, image_id: str, ext: str = '.webp') -> ImageInfo
    
    @classmethod
    def from_env(cls, logger: logging.Logger | None = None) -> "Client"

CLI 命令

nodeimage [OPTIONS] COMMAND [ARGS]...

命令:
  debug    显示调试信息和配置状态
  upload   上传图片文件、URL或文件夹
  list     列出已上传的图片，支持多种输出格式
  download 下载图片到本地（支持管道输入）
  delete   根据ID删除图片（不可撤销，支持管道输入）

选项:
  --api-key TEXT  NodeImage API 密钥
  --help          显示帮助信息并退出

输出格式 (list命令):
  id      仅显示图片ID（默认，适合管道操作）
  json    显示完整JSON信息
  csv     导出为CSV格式
  xlsx    导出为Excel格式

管道支持:
  download 和 delete 命令支持从标准输入读取图片ID列表
  使用方式: nodeimage list | nodeimage download --yes
  重要提醒: 管道操作时必须使用 --yes 参数，否则会因无法交互确认而失败

依赖项

NodeImage 依赖以下库：

• httpx - 用于 HTTP 请求（包含 SOCKS 代理支持）
• click - 用于 CLI 界面
• python-dotenv - 用于 .env 文件支持
• typing_extensions - 用于增强类型提示
• openpyxl - 用于 Excel 文件导出功能

获取 API 密钥

1. 访问 NodeImage 官网
2. 注册账户或登录现有账户
3. 在用户面板中获取您的 API 密钥

常见问题

上传失败怎么办？

请检查：

• API 密钥是否正确设置
• 图片文件是否存在且可读
• 网络连接是否正常
• 图片格式是否支持

如何查看详细错误信息？

可以通过 Python 代码捕获异常获取详细信息：

try:
    client.upload_image("image.jpg")
except Exception as e:
    print(f"详细错误: {e}")

导出Excel文件时提示缺少依赖怎么办？

如果使用 nodeimage list -f xlsx 时提示缺少 openpyxl 依赖，请运行：

pip install openpyxl

有文件大小限制吗？

具体限制请参考 NodeImage 官网 的服务条款。

许可证

本项目采用 MIT 许可证 进行许可。