<!-- Canonical URL: https://ask.atlascloud.ai/zh-TW/migrate-sora-api-app-to-seedance-or-wan -->

# 如何把使用 Sora API 的影片應用程式遷移到 Seedance 或 Wan？

> 從 Sora 遷移到 Seedance 或 Wan 時，應把穩定的內部影片 job contract 與供應商 payload 分開。透過 adapter 對應 prompt、輸入、時長、尺寸、音訊與狀態，儲存每個外部任務 ID，並以固定回歸集比較合格輸出後才移轉流量。

<!-- Canonical URL: https://ask.atlascloud.ai/migrate-sora-api-app-to-seedance-or-wan -->

# 如何把使用 Sora API 的影片應用程式遷移到 Seedance 或 Wan？

最安全的遷移應該只改變供應商 adapter，而不是產品其他部分。為 prompt、來源媒體、時長、方向、音訊意圖和交付保留統一內部影片 job contract，再在邊緣把它轉換為 Sora、Seedance 或 Wan 要求。

不要只把 `sora-2` 換成另一個模型字串並傳送相同 payload。這些 API 都使用非同步任務模式，但 endpoint、要求格式、允許值、媒體欄位與狀態回應各不相同。

## 盤點應用程式依賴的 Sora 行為

OpenAI 目前 [Videos API 參考](https://platform.openai.com/docs/api-reference/videos)記錄了透過 `POST /v1/videos` 建立任務、按影片 ID 取得狀態，以及 `prompt`、`input_reference`、`model`、`seconds` 和 `size` 等欄位。你的應用程式還可能依賴 remix、下載、SDK 回應物件或 OpenAI 特定錯誤。

撰寫替代方案前，記錄真實依賴：

| 依賴 | 需要回答的問題 |
|---|---|
| 模型 | 程式碼是否固定為 `sora-2` 或 `sora-2-pro`？ |
| 輸入 | 只有文字、一張參考圖，還是既有影片？ |
| 時長 | 正式環境實際出現哪些要求值？ |
| 尺寸 | UI 儲存像素、畫面比例還是命名 preset？ |
| 音訊 | 產品是否承諾生成音訊，還是後續替換？ |
| 狀態 | 哪些供應商狀態對應為本機狀態？ |
| 輸出 | 結果被串流、下載、複製還是按 URL 引用？ |
| 失敗 | 哪些錯誤會重試、顯示或升級處理？ |

盤點可以說明這次遷移只是更換模型，還是同時改變 workflow。

## 定義供應商中立的影片任務

建立代表產品意圖的內部物件，不要假設每個供應商都支援相同控制項。

```json
{
  "job_id": "vid_01J...",
  "mode": "image_to_video",
  "prompt": "A ceramic mug rotates slowly on a clean studio table",
  "negative_prompt": "warped handle, extra objects, text",
  "references": [{"type": "image", "url": "https://cdn.example/mug.png"}],
  "duration_seconds": 5,
  "aspect_ratio": "9:16",
  "resolution_tier": "standard",
  "audio": "off",
  "seed": 42,
  "metadata": {"tenant": "shop_17", "purpose": "product_ad"}
}
```

把 capability 標為必需、偏好或選用。若使用者明確要求參考圖，靜默丟棄就是產品錯誤；若 seed 只對一個供應商有用，adapter 可以省略，但要記錄這項決定。

## 對應意圖而不是欄位名稱

Sora 透過 `size` 使用像素尺寸。Seedance 變體可能開放 `ratio`、`resolution`、`duration`、參考陣列和音訊控制；Wan route 根據模型使用 `size` 或 `ratio`，也可能提供 prompt 擴展、shot type、參考媒體或編輯輸入。

| 產品意圖 | Sora 範例 | Seedance 或 Wan 對應 |
|---|---|---|
| 模型 | `sora-2` | 精確即時 Atlas model ID |
| 提交 | `POST /v1/videos` | `POST /api/v1/model/generateVideo` |
| Prompt | `prompt` | 通常為 `prompt` |
| 參考圖 | `input_reference` | Route 特定 `image` 或 `reference_images` |
| 時長 | `seconds` | Route 特定 `duration` 與允許範圍 |
| 畫面形狀 | `size` | `ratio`、`size`，或解析度加比例 |
| 音訊 | 模型行為 | Route 特定 `generate_audio` 或音訊輸入 |
| 結果鍵 | 影片 ID | 回應中的 prediction ID |
| 狀態 | 影片狀態 endpoint | `GET /api/v1/model/prediction/{id}` |

這張表是遷移檢查表，不是 request schema。精確允許值要從所選即時模型頁複製。

## 有目的地選擇 Seedance route

Seedance 是一個系列，而不是可互換 endpoint。Atlas Cloud 目前提供多種文字、圖片和參考 workflow。例如 [Seedance 2.0 Fast 參考生影片](https://www.atlascloud.ai/models/bytedance/seedance-2.0-fast/reference-to-video?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=migrate-sora-api-app-to-seedance-or-wan)接受參考媒體，並開放時長、解析度、畫面比例、bitrate 和音訊等 route 特定控制項。

以下產品重點適合考慮 Seedance：

* 短視聽片段；
* 參考驅動的主體、風格或場景引導；
* 社群和廣告格式；
* 在快速迭代和高品質 route 間選擇。

不要推斷每個 Seedance 變體接受相同輸入。按模式選擇 route，並在提交前用該 route schema 驗證任務。

## 有目的地選擇 Wan route

Wan 提供多種生成與編輯路徑。[Atlas Cloud Wan 頁面](https://www.atlascloud.ai/models/wan-3.0?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=migrate-sora-api-app-to-seedance-or-wan)目前既包含較新的 Wan 3.0 選項，也有較早版本；具體 endpoint 定義文生影片、圖生影片、參考或影片編輯行為。

以下需求適合考慮 Wan：

* 廣泛的生成和編輯模式；
* 在支援 route 上使用明確 prompt 擴展或鏡頭控制；
* 參考或來源影片 workflow；
* 用第二個模型系列進行品質或可用性 routing。

第一次遷移應選擇一個精確 endpoint。模糊的 `wan` adapter 最終會變成難以測試的隱藏條件集合。

## 實作明確 adapter

把驗證放在 adapter 附近。下面的簡化 Python 範例展示邊界，而不虛構每個 route 欄位。

```python
def to_atlas_payload(job, route):
    payload = {
        "model": route.model_id,
        "prompt": job["prompt"],
    }

    if job.get("duration_seconds") is not None:
        payload[route.duration_field] = route.map_duration(job["duration_seconds"])

    if job.get("aspect_ratio"):
        route.apply_frame_shape(payload, job["aspect_ratio"], job.get("resolution_tier"))

    if job.get("references"):
        route.apply_references(payload, job["references"])

    if job.get("audio") != "unspecified":
        route.apply_audio(payload, job["audio"])

    route.validate(payload)
    return payload
```

Route 設定應拒絕不支援的必要條件，而不是靜默把 12 秒改成 5 秒、把橫向變為直向或忽略參考素材。

同時保存內部任務和實際外發 payload，才能重現品質退化與計費問題。

## 保留非同步任務安全性

Atlas Cloud 會為媒體任務傳回 prediction ID，並在 [Predictions 指南](https://www.atlascloud.ai/docs/en/predictions?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=migrate-sora-api-app-to-seedance-or-wan)中說明生命週期。應用程式應使用持久本機狀態，而不是讓供應商狀態散佈各處。

| 本機狀態 | 含義 |
|---|---|
| `ready` | 已驗證但未提交 |
| `submitted` | 已保存外部任務 ID |
| `processing` | 供應商報告處理中 |
| `succeeded` | 已取得輸出 metadata |
| `failed` | 供應商傳回終止錯誤 |
| `rejected` | 已完成但未通過品質門檻 |

提交前建立 idempotency key，在同一持久記錄中保存供應商、route、外發 payload hash 和外部任務 ID。如果 worker 提交後斷線，它必須檢查已存任務，而不是建立付費要求。

使用遞增間隔與 jitter 輪詢。更頻繁查詢不會讓影片更快完成，只會增加負載。

## 建立遷移回歸集

選取 20 到 50 個代表真實流量的任務，包括高難度情況。在各供應商間保留相同來源資產和產品意圖。

為每個結果評分：

* Prompt 遵循；
* 主體和產品一致性；
* 動作穩定性；
* 時間連續性；
* 參考還原度；
* 要求音訊時的視聽配合；
* 裁切與解析度適用性；
* 首尾畫格可剪輯性；
* 完成時間分佈；
* 每個合格輸出的總成本。

不要只比較一條展示片。隨機性會讓供應商顯得異常好或壞。產品允許重試時，應重複嘗試。

## 使用可 rollback 的流量計畫

從離線測試分階段進入正式環境。

1. 離線重播已存且不敏感的 prompt。
2. 執行不會送達使用者的 shadow job。
3. 把小比例 canary 流量傳送到一個新 route。
4. 比較錯誤、完成時間、接受率和成本。
5. 只有門檻穩定時才擴大流量。
6. 在不再需要 rollback 前保留 Sora adapter。

還要決定是否向使用者顯示供應商名稱。模型差異顯著時，提供模型選擇可能更誠實有用；若產品販售的是 capability，則只能在滿足同一驗收協議的替代方案間 routing。

## 結論

從 Sora 遷移到 Seedance 或 Wan，應保留供應商中立影片任務，只替換 adapter。明確對應 capability，選擇一個真實 Atlas endpoint，保存每個 prediction ID，拒絕不支援的要求，並用固定回歸集比較每個合格輸出的成本。

Seedance 和 Wan 不是只改模型名稱就能使用的替代品。只有當應用程式把供應商 schema 當作實作細節並保持遷移可 rollback 時，它們才會成為安全選擇。

## FAQ

### 只更換 Sora 模型名稱並保留相同 request body 可以嗎？

不可以。Sora、Seedance 與 Wan 使用不同 model ID、endpoint、欄位、值與媒體輸入。保留內部 job schema，並為每條路徑撰寫 adapter。

### 這些 API 最大的共同架構是什麼？

影片生成是非同步的。應用程式送出 job、儲存外部 ID、稍後檢查狀態，並且只在完成後取得輸出。

### 哪些欄位必須明確對應？

對應 model ID、prompt、參考媒體、時長、比例或尺寸、解析度、音訊、seed、安全行為與供應商狀態。不要默默忽略不支援欄位。

### 應選 Seedance 還是 Wan？

用真實應用程式工作測試兩者。Seedance 適合參考驅動的短片與視聽任務，Wan 提供多種文字、圖片、參考與編輯路徑。以合格輸出決定。

### 遷移時如何避免重複付費 job？

建立內部 idempotency key，送出後立即儲存 provider ID，並在重試前檢查既有 job。網路不確定性不應觸發盲目重送。

### 最初應遷移多少流量？

從離線回歸 prompt 開始，再使用小比例 shadow 或 canary。只有合格率、錯誤、完成時間與成本維持門檻時才擴大。