Welcome to the AiVideoAPI Platform. We provide enterprise-level multimodal video generation capabilities, including Text-to-Video, Image-to-Video, and Video-to-Video editing with audio support.

歡迎使用 AiVideoAPI 平臺。我們提供企業級的多模態視頻生成能力，支持文生視頻、圖生視頻、視頻編輯及擴展（可附帶音頻輸入）。

2. Authentication2. 接口鑑權

All API requests must include your platform-issued API Key in the HTTP Authorization header.

所有接口請求必須在請求頭 Authorization 中攜帶本平臺下發的 API Key（以 sk- 開頭）。

Authorization: Bearer sk-your-api-key-here

3. Pricing3. 計費說明

Cost is calculated based on token consumption. The token count is determined by output video duration, resolution, and frame rate.

費用按 Token 消耗計算。Token 數量由輸入視頻時長、輸出視頻時長、分辨率及幀率綜合決定。純文本/圖片/音頻輸入不計費，僅按最終生成的視頻計費。

• Text/Image-to-Video: Billed at standard generation rates.文/圖生視頻: 按基礎生成費率扣費。
• Video-to-Video: Includes a minimum token limit.視頻生視頻: 按視頻編輯費率扣費，包含最低 Token 消耗限制。

注：您的實際扣費將基於模型使用費率計算，任務完成（completed）時實時從餘額扣除。

4. Supported Models4. 支持的模型

5. Create Generation Task5. 創建生成任務

POST /contents/generations/tasks

Submit a video generation task. This is an asynchronous API.

提交視頻生成任務。此接口爲異步接口，返回任務 ID，需通過查詢接口獲取最終視頻。

Request Body Parameters請求體參數 (Body)

Content Array Object TypesContent 數組對象說明

• 文本 (text): {"type": "text", "text": "提示詞描述"}
• 圖片 (image_url): {"type": "image_url", "image_url": {"url": "圖片鏈接 或 asset://<Asset_Id>"}, "role": "reference_image"} (最多9張)
• 視頻 (video_url): {"type": "video_url", "video_url": {"url": "視頻鏈接 或 asset://<Asset_Id>"}, "role": "reference_video"} (最多3個，總長不超15s)
• 音頻 (audio_url): {"type": "audio_url", "audio_url": {"url": "音頻鏈接 或 asset://<Asset_Id>"}, "role": "reference_audio"} (必須配合圖/視頻使用)

• Text: {"type": "text", "text": "prompt"}
• Image: {"type": "image_url", "image_url": {"url": "URL or asset://<Asset_Id>"}, "role": "reference_image"} (Max 9)
• Video: {"type": "video_url", "video_url": {"url": "URL or asset://<Asset_Id>"}, "role": "reference_video"} (Max 3)
• Audio: {"type": "audio_url", "audio_url": {"url": "URL or asset://<Asset_Id>"}, "role": "reference_audio"}

Example: Text to Video示例 1：文生視頻 (Text to Video)

curl -X POST "https://api.sdapi.ai/api/v3/contents/generations/tasks" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-your-api-key" \
-d '{
    "model": "AiVideoMax",
    "duration": 5,
    "ratio": "16:9",
    "content": [
        {
            "type": "text",
            "text": "A cute cat walking gracefully on the street, cinematic lighting, 4k."
        }
    ]
}'

Example: Multimodal Video Edit示例 2：多模態視頻編輯 (視頻+圖片+文本)

curl -X POST "https://api.sdapi.ai/api/v3/contents/generations/tasks" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-your-api-key" \
-d '{
    "model": "AiVideoMin",
    "generate_audio": true,
    "content": [
        {
            "type": "text",
            "text": "The cat from [Image1] replaces the person in [Video1], walking identically."
        },
        {
            "type": "video_url",
            "video_url": { "url": "https://example.com/reference_video.mp4" },
            "role": "reference_video"
        },
        {
            "type": "image_url",
            "image_url": { "url": "https://example.com/cat_image.png" },
            "role": "reference_image"
        }
    ]
}'

Response Example響應示例

{
    "code": 0,
    "msg": "Success",
    "data": {
        "id": "cgt-2026123456789"
    }
}

6. Query Task6. 查詢任務狀態

GET /contents/generations/tasks/{task_id}

Poll this endpoint every few seconds to check the task status. Download the video once status is completed.

通過返回的 Task ID 輪詢此接口獲取任務狀態。狀態爲 completed 時，即可獲取生成的視頻鏈接（請在24小時內下載保存）。

Status Values任務狀態說明 (status)

Response Example (Completed)響應示例 (任務完成)

{
    "code": 0,
    "msg": "Success",
    "data": {
        "id": "cgt-2026123456789",
        "status": "completed",
        "content": [
            {
                "type": "video_url",
                "video_url": {
                    "url": "https://generation-result-url.mp4"
                }
            }
        ]
    },
    "usage": {
        "completion_tokens": 10240,
        "total_tokens": 10240
    }
}

7. List Tasks7. 獲取任務列表

GET /contents/generations/tasks?page_num=1&page_size=10

Retrieve a list of your historical generation tasks.

分頁獲取當前 API Key 提交的歷史視頻生成任務記錄。

8. Assets API8. 數字資產 (Assets API)

We provide a unified interface for all Assets API operations. You can use your standard API Key (Bearer Token) to interact with digital assets.

我們爲數字資產 (Assets API) 提供了統一的調用接口。您可以使用現有的 API Key (Bearer Token) 即可管理數字資產。這些資產（圖片、音頻、視頻）的 ID 可直接用於生成視頻時的素材引用。

Core Concepts & Constraints核心概念與上傳限制

• Asset Group (資產組): 必須先創建資產組，再在組內創建具體資產。通常用於將同一角色的多張參考圖歸爲一組。
• Asset (資產): 具體的圖片、視頻或音頻。上傳後需經過模型預處理，狀態變爲 Active 後才能在生成視頻時使用。
  狀態說明 (Status):
  • Processing: 資產正在預處理中，暫不可用。
  • Active: 資產已處理完成，可用於視頻生成。
  • Failed: 資產處理失敗。
• 最佳實踐: 建議將面部特寫、全身圖、服裝細節分開上傳，不要拼接到一張圖裏，否則可能導致人臉識別失敗。（詳見下方最佳實踐示例）
• 文件限制:
  • 圖片: jpeg/png/webp 等，寬高比 0.4~2.5，分辨率 300~6000px，小於 30MB。
  • 視頻: mp4/mov，時長 2~15秒，小於 50MB，幀率 24~60fps。
• 頻率限制: CreateAsset (上傳素材) 限制 300 QPM（次/分鐘），其餘接口限制 10 QPS（次/秒）。

• Asset Group: Create a group first, then add assets to it. Useful for grouping multiple references of the same character.
• Asset: Image, video, or audio. Must be in Active status to be used.
• Best Practice: Separate facial close-ups and outfit details into different images. Do not collage them. (See best practice examples below)
• Constraints:
  • Image: jpeg/png/webp, ratio 0.4-2.5, 300-6000px, < 30MB.
  • Video: mp4/mov, 2-15s, < 50MB, 24-60fps.
• Rate Limits: CreateAsset is 300 QPM. Others are 10 QPS.

API Endpoints Reference具體接口列表與參數

POST /contents/assets/{action}

所有資產相關接口通過統一的路由調用，請在 {action} 中填入對應的接口名，並將參數放入 JSON Body 中。

All asset endpoints use a unified route. Replace {action} with the target endpoint name and provide parameters in the JSON Body.

其他支持的接口: UpdateAssetGroup (更新組名), UpdateAsset (更新資產名), DeleteAsset (刪除資產)。

Other Supported Endpoints: UpdateAssetGroup, UpdateAsset, DeleteAsset.

Workflow & Code Example (Python)完整工作流與代碼示例 (Python)

1. 創建組 -> 2. 上傳素材 -> 3. 輪詢等待 Active -> 4. 填入生成視頻接口中

1. Create Group -> 2. Upload Asset -> 3. Poll until Active -> 4. Use in Video Generation

import requests
import time

API_KEY = "sk-your-api-key"
BASE_URL = "https://api.sdapi.ai/api/v3/contents/assets"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def create_asset_and_wait():
    # 1. Create Group (Skip if you already have one)
    group_id = "group-xxxx" 
    
    # 2. Create Asset
    create_payload = {
        "GroupId": group_id,
        "URL": "https://example.com/your-image.jpg",
        "AssetType": "Image"
    }
    print("Uploading asset...")
    res = requests.post(f"{BASE_URL}/CreateAsset", headers=HEADERS, json=create_payload).json()
    asset_id = res.get("Result", {}).get("Id") or res.get("Id")
    
    # 3. Poll for Status
    print(f"Asset created: {asset_id}. Waiting for processing...")
    while True:
        status_res = requests.post(f"{BASE_URL}/GetAsset", headers=HEADERS, json={"Id": asset_id}).json()
        status = status_res.get("Result", {}).get("Status") or status_res.get("Status")
        
        if status == "Active":
            print("Asset is ready to use!")
            break
        elif status == "Failed":
            print("Asset processing failed.")
            break
        time.sleep(3)

create_asset_and_wait()

Best Practice - Uploading Private Assets最佳實踐 - 上傳私有資產

在上傳人物資產時，將目標人臉參考、全身參考和細節參考拼接到一張圖片中，會使每個參考區域過小。這增加了模型的識別難度，可能導致生成的角色與上傳的資產不匹配。在某些情況下，甚至可能導致非公衆人物人臉被誤判爲公衆人物，觸發風控攔截。

When uploading assets, combining the target face reference, full-body reference, and detail references into a single image may make each reference region too small. This increases the model's recognition difficulty and can lead to mismatches between the generated character and the uploaded asset. In some cases, it may also cause a non-celebrity face to be misclassified as a celebrity look-alike, triggering risk-control blocking.

9. Query Balance9. 查詢餘額

GET /user/balance

Check your current available account balance.

查詢當前賬戶的可用餘額。

Response Example響應示例

{
    "code": 0,
    "msg": "Success",
    "data": {
        "balance": 100.50,
        "currency": "USD"
    }
}

10. Spending Records10. 扣費記錄

GET /user/spending?page_num=1&page_size=10

Retrieve a paginated list of your billing and token consumption history for completed tasks.

分頁獲取當前賬戶的扣費明細和歷史 Token 消耗記錄（僅顯示已完成併產生費用的任務）。

Response Example響應示例

{
    "code": 0,
    "msg": "Success",
    "data": {
        "items": [
            {
                "id": "cgt-2026123456789",
                "model": "AiVideoMax",
                "call_type": "t2v",
                "tokens_used": 108900,
                "cost": 1.143,
                "created_at": "2026-04-02 21:15:00"
            }
        ],
        "total": 42,
        "page_num": 1,
        "page_size": 10
    }
}

11. Error Codes & Troubleshooting11. 錯誤碼與異常排查

本平臺接口的錯誤返回分爲兩類：同步網關錯誤 和 異步任務錯誤。

Our API errors are divided into two types: Synchronous Gateway Errors and Asynchronous Task Errors.

1. 同步網關錯誤 (Synchronous Errors)1. Synchronous Gateway Errors

在請求發起時直接返回（如參數格式不對、模型名稱無效、餘額不足），HTTP 狀態碼通常爲 4xx 或 5xx。失敗時 code 不爲 0。

Returned immediately upon request (e.g., invalid parameters, invalid model name, insufficient balance). HTTP status is usually 4xx or 5xx. On failure, code is not 0.

{
    "code": 400,
    "msg": "Invalid model name. Supported models are: AiVideoMax, AiVideoMin, AiVideoMaxNF, AiVideoMinNF, AiVideoMini, AiVideoMiniNF"
}

2. 異步任務錯誤 (Asynchronous Task Errors)2. Asynchronous Task Errors

任務提交成功後，在輪詢查詢任務狀態 (Query Task) 時，如果 status 爲 failed，會在返回的 error.code 中提供具體的失敗原因。請務必根據此處的錯誤碼調整您的請求。

When polling task status, if status is failed, the specific reason is provided in error.code. Please adjust your request according to this error code.

{
    "id": "cgt-2026123456789",
    "status": "failed",
    "error": {
        "code": "OutputVideoSensitiveContentDetected",
        "message": "The output video contains sensitive content..."
    }
}

常見異步錯誤碼清單 (Asynchronous Error Codes Reference)Asynchronous Error Codes Reference