> For the complete documentation index, see [llms.txt](https://docs.apismart.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apismart.ai/documentation/zh-tw/cheng-shi-ma-fan-li-yu-qian-yi/python.md).

# Python

了解如何使用 Python 呼叫 ApiSmart API，包括模型探索、聊天補全、串流、圖片生成、本地圖片上傳以及非同步影片任務。

使用 Python 將 ApiSmart 整合到後端服務、腳本、自動化工作流程與 AI 驅動的應用程式中。

本指南使用廣受歡迎的 `requests` 函式庫示範如何驗證請求、擷取可用模型、生成文字與圖片，以及建立非同步影片任務。

### 🚀 開始之前

請確認你已具備：

* 已安裝 Python 3
* ApiSmart 帳戶
* 有效的 API 金鑰
* 足夠的錢包餘額以供付費請求使用

安裝 `requests`:

```bash
pip install requests
```

### 🔑 設定你的 API 金鑰

避免將 API 金鑰直接硬編碼在應用程式原始碼中。

改為將它設為環境變數。

#### macOS 與 Linux

```bash
export APISMART_API_KEY="your-api-key"
```

#### Windows PowerShell

```powershell
$env:APISMART_API_KEY="your-api-key"
```

接著在 Python 中讀取它：

```python
import os

API_KEY = os.environ["APISMART_API_KEY"]
```

標準的 ApiSmart API Base URL 為：

```python
BASE_URL = "https://gw.apismart.ai/v1"
```

建立可重複使用的請求標頭：

```python
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}
```

請妥善保管你的 API 金鑰，切勿將其提交到公開儲存庫。

### 🧩 取得可用模型

在送出生成請求前，你可以取得目前的模型 ID：

```python
import os
import requests

API_KEY = os.environ["APISMART_API_KEY"]
BASE_URL = "https://gw.apismart.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
}

response = requests.get(
    f"{BASE_URL}/models",
    headers=headers,
)

response.raise_for_status()

data = response.json()

for model in data.get("data", []):
    print(model["id"])

```

API 會將模型項目以 `data[]`.

使用：

```
data[].id
```

作為 `模型` 在支援的 API 請求中的值。

模型 ID 必須完全一致。請勿更改句點 (`.`), 連字號 (`-`), 或版本號。

如需模型類別與 ID，請參閱 [**模型與模型 ID**](https://docs.apismart.ai/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-yu-mo-xing-id.md).

### 💬 聊天補全

使用：

`POST /v1/chat/completions`

範例：

```python
import os
import requests

API_KEY = os.environ["APISMART_API_KEY"]
BASE_URL = "https://gw.apismart.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "deepseek-v4-flash",
    "messages": [
        {
            "role": "user",
            "content": "你好！請介紹一下你自己。",
        }
    ],
}

response = requests.post(
    f"{BASE_URL}/chat/completions",
    headers=headers,
    json=payload,
)

response.raise_for_status()

print(response.json())
```

該 `模型` 值必須是有效的 ApiSmart 模型 ID。

如需完整的請求行為，請參閱 [**Chat Completions API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/liao-tian-bu-quan-api.md).

### 🌊 串流文字回應

Chat Completions 可透過設定以下項目支援串流：

```json
{
  "stream": true
}
```

在 Python 中 `requests`，可使用 `stream=True`:

```python
import os
import requests

API_KEY = os.environ["APISMART_API_KEY"]
BASE_URL = "https://gw.apismart.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "deepseek-v4-flash",
    "messages": [
        {
            "role": "user",
            "content": "請寫一個短篇故事。",
        }
    ],
    "stream": True,
}

with requests.post(
    f"{BASE_URL}/chat/completions",
    headers=headers,
    json=payload,
    stream=True,
) as response:
    response.raise_for_status()

    for line in response.iter_lines(decode_unicode=True):
        if line:
            print(line)
```

此範例會在串流資料到達時立即列印。

你實際使用的處理邏輯取決於你的應用程式希望如何消費與顯示串流回應。

如需 ApiSmart 回應行為概覽，請參閱 [**回應模式**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/hui-ying-mo-shi.md).

### 🖼️ 生成圖片

使用：

`POST /v1/images/generations`

範例：

```python
import os
import requests

API_KEY = os.environ["APISMART_API_KEY"]
BASE_URL = "https://gw.apismart.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "doubao-seedream-5-0",
    "prompt": "一座日出時分的山村，水彩風格",
    "size": "2K",
    "watermark": False,
}

response = requests.post(
    f"{BASE_URL}/images/generations",
    headers=headers,
    json=payload,
    timeout=120,
)

response.raise_for_status()

result = response.json()

print(result)
```

圖片生成預設為同步。

單次生成通常約需 20–40 秒，而高解析度或多圖片請求可能需要更久。

用戶端逾時時間至少設為 **90 秒**。上方範例使用：

```python
timeout=120
```

以提供額外的生成時間。

### 🔄 根據參考圖片生成

請使用公開圖片網址： `image`:

```python
payload = {
    "model": "doubao-seedream-5-0",
    "prompt": "將這張圖片轉換為水彩畫",
    "image": "https://example.com/input.jpg",
    "size": "2048x2048",
}

response = requests.post(
    f"{BASE_URL}/images/generations",
    headers=headers,
    json=payload,
    timeout=120,
)

response.raise_for_status()

print(response.json())
```

在支援的情況下，也可以陣列形式提供多張參考圖片。

如需圖片限制與參數，請參閱 [**Image Generation API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/tu-pian-sheng-cheng-api.md).

### 📤 上傳本機圖片

本機圖片上傳使用：

`POST /v1/images/edits`

此端點使用 multipart form data，而非 JSON 請求本文。

```python
import os
import requests

API_KEY = os.environ["APISMART_API_KEY"]
BASE_URL = "https://gw.apismart.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
}

data = {
    "model": "doubao-seedream-5-0",
    "prompt": "將角色放入賽博龐克環境中",
    "size": "2K",
    "response_format": "url",
}

with open("character.png", "rb") as image_file:
    files = {
        "image": ("character.png", image_file),
    }

    response = requests.post(
        f"{BASE_URL}/images/edits",
        headers=headers,
        data=data,
        files=files,
        timeout=120,
    )

response.raise_for_status()

print(response.json())
```

請勿手動設定：

```
Content-Type: application/json
```

用於 multipart 檔案上傳。

該 `requests` 函式庫會在你使用 `files=`.

每個上傳的圖片都必須符合文件中記載的限制： [**Image Generation API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/tu-pian-sheng-cheng-api.md).

### 🎬 建立影片任務

影片生成是非同步的。

建立任務時請使用：

`POST /v1/video/tasks`

範例：

```python
import os
import requests

API_KEY = os.environ["APISMART_API_KEY"]
BASE_URL = "https://gw.apismart.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "happyhorse-1.0",
    "prompt": "一座夜晚的微型城市，火車穿行在街道之間",
    "duration": 5,
    "size": "720p",
}

response = requests.post(
    f"{BASE_URL}/video/tasks",
    headers=headers,
    json=payload,
)

response.raise_for_status()

task = response.json()

print(task)
```

請儲存 API 回傳的任務 ID，以便查詢生成狀態。

對於解析度與時長會影響計費的模型，請明確提供這些值，而不要依賴預設值。

### 🔄 查詢影片任務

使用：

`GET /v1/video/tasks/{id}`

範例：

```python
task_id = "task_xxxxxx"

response = requests.get(
    f"{BASE_URL}/video/tasks/{task_id}",
    headers={
        "Authorization": f"Bearer {API_KEY}",
    },
)

response.raise_for_status()

print(response.json())
```

可能的任務狀態包括：

* `queued`
* `running`
* `succeeded`
* `failed`
* `cancelled`
* `expired`

### ⏳ 輪詢直到影片生成完成

你可以持續輪詢該任務，直到它進入最終狀態：

```python
import os
import time
import requests

API_KEY = os.environ["APISMART_API_KEY"]
BASE_URL = "https://gw.apismart.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
}

task_id = "task_xxxxxx"

while True:
    response = requests.get(
        f"{BASE_URL}/video/tasks/{task_id}",
        headers=headers,
    )

    response.raise_for_status()

    task = response.json()
    status = task.get("status")

    print("狀態：", status)

    if status == "succeeded":
        print("結果：", task)
        break

    if status in {"failed", "cancelled", "expired"}:
        print("任務結束：", task)
        break

    time.sleep(5)
```

此範例在每次狀態檢查之間等待 5 秒。

如需完整的 HappyHorse 與 Seedance 工作流程，請參閱 [**影片生成 API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/ying-pian-sheng-cheng-api.md).

### 🕘 擷取近期生成的圖片

使用：

`GET /v1/images`

```python
response = requests.get(
    f"{BASE_URL}/images",
    headers={
        "Authorization": f"Bearer {API_KEY}",
    },
    params={
        "page": 1,
        "page_size": 20,
    },
)

response.raise_for_status()

print(response.json())
```

### 🕘 擷取近期生成的影片

使用：

`GET /v1/videos`

```python
response = requests.get(
    f"{BASE_URL}/videos",
    headers={
        "Authorization": f"Bearer {API_KEY}",
    },
    params={
        "page": 1,
        "page_size": 20,
    },
)

response.raise_for_status()

print(response.json())
```

如需歷史欄位與可用性限制，請參閱 [**已生成媒體歷史紀錄**](https://docs.apismart.ai/documentation/zh-tw/api-shi-yong-liang/sheng-cheng-mei-ti-li-shi.md).

### ⚠️ 處理 API 錯誤

使用 `raise_for_status()` 以偵測失敗的 HTTP 回應：

```python
response = requests.get(
    f"{BASE_URL}/models",
    headers={
        "Authorization": f"Bearer {API_KEY}",
    },
)

try:
    response.raise_for_status()
except requests.HTTPError:
    print("HTTP 狀態：", response.status_code)
    print("回應：", response.text)
    raise
```

常見的 API 回應包括：

| 狀態            | 範例程式碼                   | 含義              |
| ------------- | ----------------------- | --------------- |
| `400`         | `invalid_request_error` | 無效的請求           |
| `401`         | `invalid_api_key`       | 無效的 API 金鑰      |
| `402`         | `insufficient_quota`    | 餘額不足            |
| `403`         | `model_not_allowed`     | 此 API 金鑰無法使用該模型 |
| `429`         | `rate_limit_error`      | 請求速率超出限制        |
| `502` / `504` | 閘道錯誤                    | 暫時性的上游或網路問題     |
| `503`         | 服務不可用                   | 供應商或相依服務暫時無法使用  |

如需完整的錯誤處理指引，請參閱 [**HTTP 狀態碼與 API 錯誤**](https://docs.apismart.ai/documentation/zh-tw/yi-nan-pai-jie/http-zhuang-tai-ma-yu-api-cuo-wu.md).

### 🔁 重試暫時性失敗

部分 `5xx` 錯誤可能是暫時性的。

重試暫時性失敗時：

* 在每次嘗試之間加入延遲
* 對重複重試使用指數退避
* 遵循 `Retry-After` 當 API 提供時
* 未修正請求之前，不要自動重試無效參數或驗證錯誤

簡單的重試結構可能如下：

```python
import time
import requests

for attempt in range(3):
    response = requests.get(
        f"{BASE_URL}/models",
        headers={
            "Authorization": f"Bearer {API_KEY}",
        },
    )

    if response.status_code < 500:
        break

    time.sleep(2 ** attempt)

response.raise_for_status()
```

請根據端點與你的應用程式需求調整重試行為。

### ✅ Python 整合檢查清單

在部署整合之前，請確認：

* 你的 API 金鑰已安全儲存
* Base URL 正確
* 模型 ID 已完整複製
* JSON 請求使用正確的標頭
* multipart 上傳不會強制使用 `application/json`
* 圖片請求使用適當的逾時時間
* 影片請求會儲存並輪詢回傳的任務 ID
* 暫時性錯誤使用適當的重試策略
* 你的帳戶有足夠的錢包餘額

### ➡️ 後續步驟

接著查看：

* [**API 基礎**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/api-ji-chu.md) — 了解常見的 API 慣例
* [**模型與模型 ID**](https://docs.apismart.ai/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-yu-mo-xing-id.md) — 找出有效的模型 ID
* [**Chat Completions API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/liao-tian-bu-quan-api.md) — 檢視文字生成行為
* [**Image Generation API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/tu-pian-sheng-cheng-api.md) — 探索圖片生成與編輯
* [**影片生成 API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/ying-pian-sheng-cheng-api.md) — 建立非同步影片工作流程
* [**回應模式**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/hui-ying-mo-shi.md) — 了解標準、串流與非同步回應
* [**已生成媒體歷史紀錄**](https://docs.apismart.ai/documentation/zh-tw/api-shi-yong-liang/sheng-cheng-mei-ti-li-shi.md) — 擷取近期生成的媒體
