> ## 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 Image 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 Raw Bytes 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)

我們隨時為您提供協助！