文件字段格式說明

文件（像圖片、音頻、視頻）作為入參數支持以下兩種格式的參數傳遞：

1. URL 格式

   • 說明：通過一個外部鏈接來引用文件資源。該 URL 應該是一個可訪問的網絡地址，并且指向的是一個有效的文件。

   • 示例：

     json復制代碼{
       "image": "https://example.com/image.jpg"
     }
     

   • 注意事項：

     • 確保 URL 是公開可訪問的，避免私有網絡或受限訪問的 URL。

     • 傳遞 URL 時，請確保提供對應文件資源的服務網絡連接穩定，避免因為網絡問題導致文件讀取失敗。

2. Base64 Data URI 格式

   • 說明：直接將文件數據以 Base64 編碼的形式嵌入到請求中。這種方式適用于文件較小且希望直接在請求中攜帶文件數據的場景。

   • 示例：

     json復制代碼{
       "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD/..."
     }
     

   • 注意事項：

     • Base64 編碼后的數據可能較大，建議在圖片較小時使用此格式。

     • 請確保文件數據的編碼正確，并且帶有正確的 MIME 類型前綴（如 data:image/jpeg;base64,）。

     • 使用 Base64 編碼會增加請求的大小，可能對請求性能產生影響，建議僅在需要時使用。

使用建議

• 對于大多數情況，建議使用 URL 格式，因為它能減少請求的體積，并且更適合引用已托管的文件資源。

• Base64 Data URI 格式更適合于希望將文件數據直接嵌入到請求中的場景，如在數據保密或短期臨時使用的場景下。

附錄

以下提供一個將本地圖片轉成 Base64 Data URI 的 Python 工具類實現

import base64
import os

def get_photo_base64(image_path, image_format=None):
    """
    將圖像文件轉換為Base64編碼的數據URI

    參數:
    image_path (str): 圖像文件的路徑
    image_format (str, optional): 圖像格式，如果未提供，將根據文件擴展名自動檢測

    返回:
    str: Base64編碼的數據URI
    """

    # 打開圖像文件
    with open(image_path, "rb") as image_file:
        image_data = image_file.read()

    # 如果未指定圖像格式，從文件擴展名中獲取
    if not image_format:
        _, extension = os.path.splitext(image_path)
        image_format = extension.lstrip(".")

    # 生成Base64編碼的數據URI
    base64_data = base64.b64encode(image_data).decode('utf-8')
    data_uri = f"data:image/{image_format.upper()};base64,{base64_data}"

    return data_uri


print(get_photo_base64('/xxx/xxx.png'))
print(get_photo_base64('/xxx/xxx.jpeg', "jpeg"))