> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python

[![PyPI - Version](https://img.shields.io/pypi/v/sunra_client)](https://pypi.org/project/sunra_client)

### 介绍

Python 客户端库提供了一个易于使用的接口来与 Sunra 的服务交互。

### 安装

要将客户端集成到您的项目中，请使用 pip 安装：

```bash theme={null}
pip install sunra-client
```

### 功能

#### 调用端点

Sunra 通过队列系统管理端点请求，确保可靠性和可扩展性。使用 `subscribe` 方法提交请求并等待结果。

**示例：**

```python theme={null}
import sunra_client

result = sunra_client.subscribe(
    "black-forest-labs/flux-kontext-pro/text-to-image",
    arguments={
    	"prompt": '一个吉卜力风格的海边小镇，有彩色房屋，晾衣绳飘扬，猫咪在窗台上睡觉。',
    	"width": 1024,
    	"height": 768,
    	"output_format": 'jpeg'
    },
    with_logs=True,
    on_enqueue=print,
    on_queue_update=print,
)
print(result)
```

#### 队列管理

使用这些方法管理您的请求：

##### 提交请求

提交请求并检索 `request_id` 以供后续使用。

**示例：**

```python theme={null}
import sunra_client

handler = sunra_client.submit(
    "black-forest-labs/flux-kontext-pro/text-to-image",
    arguments={
      "prompt": '一个吉卜力风格的海边小镇，有彩色房屋，晾衣绳飘扬，猫咪在窗台上睡觉。',
      "width": 1024,
      "height": 768,
      "output_format": 'jpeg'
    },
    webhook_url="https://optional.webhook.url/for/results",
)
request_id = handler.request_id
```

##### 检查请求状态

检索请求的状态。

**示例：**

```python theme={null}
import sunra_client
status = sunra_client.status(request_id, with_logs=True)
```

##### 检索请求结果

获取已完成请求的结果。

**示例：**

```python theme={null}
import sunra_client
result = sunra_client.result(request_id)
```

#### 文件上传

上传文件以获取URL用于异步请求。这对于处理文件的模型（如图像转视频或语音转文本转换器）是必需的。

<Note>最大文件大小：100MB</Note>

##### 上传本地文件

您可以轻松地从本地文件系统上传文件。这对于处理本地数据的脚本或应用程序很有用。

```python theme={null}
import sunra_client

# 初始化同步客户端
client = sunra_client.SyncClient()

try:
  # 从给定路径上传文件
  file_url = client.upload_file(path="path/to/your/image.png")
  print(f"文件上传成功：{file_url}")
  # 此URL现在可以与模型端点一起使用
except FileNotFoundError:
  print("错误：在指定路径未找到文件。")
except Exception as e:
  print(f"发生错误：{e}")
```

##### 上传内存中的数据

您还可以上传保存在内存中的数据，例如使用 PIL (Pillow) 创建的图像内容或在 Web 请求中收到的文件。

<CodeGroup>
  ```python PIL图像 theme={null}
  import sunra_client
  from PIL import Image
  import io

  # 初始化同步客户端
  client = sunra_client.SyncClient()

  # 在内存中创建图像，例如使用 Pillow
  image = Image.new("RGB", (600, 400), color = 'red')
  byte_arr = io.BytesIO()
  image.save(byte_arr, format='PNG')
  image_bytes = byte_arr.getvalue()

  # 使用 `upload` 方法上传内存中的图像数据
  image_url = client.upload(
      data=image_bytes,
      content_type="image/png"
  )
  print(f"图像上传成功：{image_url}")
  ```

  ```python 原始字节 theme={null}
  import sunra_client

  # 初始化同步客户端
  client = sunra_client.SyncClient()

  # 您可能从读取文件或 Web 请求中获得的原始字节
  raw_data = b"some file content here"

  # 上传原始字节
  data_url = client.upload(
      data=raw_data,
      content_type="application/octet-stream"
  )
  print(f"数据上传成功：{data_url}")
  ```
</CodeGroup>

### 支持

加入我们的社区获得帮助或讨论：

* **Discord 社区**：[加入我们](https://discord.gg/897qCzvCcU)
* **GitHub 仓库**：[访问这里](https://github.com/sunra-ai/sunra-clients)

我们在这里为您提供帮助！