--- title: Luma 修改影片 | RunAPI description: 使用影片修改端點建立非同步 Task。 url: https://runapi.ai/zh-TW/docs/api/luma/modify-video.md canonical: https://runapi.ai/zh-TW/docs/api/luma/modify-video locale: zh-TW --- > HTML 版本: https://runapi.ai/zh-TW/docs/api/luma/modify-video > 代理程式網站索引: https://runapi.ai/llms.txt # Luma 修改影片 ## 概覽 使用影片修改端點搭配支援的模型。使用回傳的 Task ID 擷取其狀態，或提供 callback_url 以接收下方說明的回呼通知。 ### 快速入門 1. 建立 API 金鑰並將其設定為 RUNAPI_API_KEY。 2. 選擇支援的模型，並傳送本文符合該模型結構描述的 POST 請求。 3. 儲存返回的任務 ID，然後輪詢直到終止狀態，或處理下方說明的回呼。 ## 端點 POST /api/v1/luma/modify_video 基礎 URL: https://runapi.ai API 版本: v1 身分驗證: Authorization: Bearer YOUR_API_TOKEN ## 支援的模型 開啟模型頁面以查看目前的定價、速率限制及商業用途詳情。 - [Luma](https://runapi.ai/zh-TW/models/luma) ## 請求綱要 欄位及允許值取決於所選模型。若提供 callback_url，其將接收下方記錄的 Task 交付內容。 ### luma-modify-video ```json { "callback_url": { "type": "string" }, "model": { "type": "string" }, "prompt": { "required": true, "type": "string" }, "source_video_url": { "required": true, "type": "string" }, "watermark": { "type": "string" } } ``` ## 建立接受記錄 HTTP 202 - POST /api/v1/luma/modify_video ### 回應綱要 ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "id": { "type": "string" }, "status": { "enum": [ "processing" ], "type": "string" }, "task_replayed": { "type": "boolean" } }, "required": [ "id", "status", "billing" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "id": "tsk_reference_demo", "status": "processing" } ``` ## 輪詢處理中 HTTP 200 - GET /api/v1/luma/modify_video/:id ### 回應綱要 ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "id": { "type": "string" }, "status": { "enum": [ "processing" ], "type": "string" } }, "required": [ "id", "status", "billing" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "id": "tsk_reference_demo", "status": "processing" } ``` ## 輪詢已完成 HTTP 200 - GET /api/v1/luma/modify_video/:id ### 回應綱要 ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "id": { "type": "string" }, "sources": { "items": { "properties": { "url": { "type": "string" } }, "required": [ "url" ], "type": "object", "unevaluatedProperties": false }, "type": "array" }, "status": { "enum": [ "completed" ], "type": "string" }, "videos": { "items": { "properties": { "url": { "type": "string", "x-runapi-generated-media": true } }, "required": [ "url" ], "type": "object", "unevaluatedProperties": false }, "type": "array" } }, "required": [ "id", "status", "videos", "billing" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "id": "tsk_reference_demo", "status": "completed", "videos": [ { "url": "https://file.runapi.ai/reference-video.mp4" } ] } ``` ## 輪詢失敗 HTTP 200 - GET /api/v1/luma/modify_video/:id ### 回應綱要 ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "type": "string" }, "id": { "type": "string" }, "status": { "enum": [ "failed" ], "type": "string" } }, "required": [ "id", "status", "error", "billing" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "error": "Task processing failed.", "id": "tsk_reference_demo", "status": "failed" } ``` ## 客戶回呼：已完成 HTTP 200 - POST callback_url ### 回應綱要 ```json { "properties": { "id": { "type": "string" }, "sources": { "items": { "properties": { "url": { "type": "string" } }, "required": [ "url" ], "type": "object", "unevaluatedProperties": false }, "type": "array" }, "status": { "enum": [ "completed" ], "type": "string" }, "videos": { "items": { "properties": { "url": { "type": "string", "x-runapi-generated-media": true } }, "required": [ "url" ], "type": "object", "unevaluatedProperties": false }, "type": "array" } }, "required": [ "id", "status", "videos" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "id": "tsk_reference_demo", "status": "completed", "videos": [ { "url": "https://file.runapi.ai/reference-video.mp4" } ] } ``` ## 客戶回呼：失敗 HTTP 200 - POST callback_url ### 回應綱要 ```json { "properties": { "error": { "oneOf": [ { "type": "string" }, { "properties": { "code": { "type": "string" }, "limit_cents": { "type": "integer" }, "message": { "type": "string" }, "reset_at": { "format": "date-time", "type": [ "string", "null" ] }, "used_cents": { "type": "integer" }, "window": { "enum": [ "1h", "1d", "7d", "daily", "weekly", "monthly", "lifetime" ], "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } ] }, "id": { "type": "string" }, "status": { "enum": [ "failed" ], "type": "string" } }, "required": [ "id", "status", "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": { "code": "generation_failed", "message": "Task processing failed." }, "id": "tsk_reference_demo", "status": "failed" } ``` ## 錯誤 HTTP 401 - POST /api/v1/luma/modify_video ### 回應綱要 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "Authentication required" } ``` ## 錯誤 HTTP 401 - GET /api/v1/luma/modify_video/:id ### 回應綱要 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "Authentication required" } ``` ## 錯誤 HTTP 400 - POST /api/v1/luma/modify_video ### 回應綱要 ```json { "oneOf": [ { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false }, { "properties": { "error": { "description": "人類可讀的驗證摘要。", "type": "string" }, "errors": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "description": "以公開請求欄位為索引鍵的驗證訊息，每個欄位包含一組人類可讀的字串陣列。", "type": "object" } }, "required": [ "error", "errors" ], "type": "object", "unevaluatedProperties": false } ] } ``` ### 回應範例 ```json { "error": "model must be one of: luma-modify-video" } ``` ## 錯誤 HTTP 402 - POST /api/v1/luma/modify_video ### 回應綱要 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "Insufficient balance" } ``` ## 錯誤 HTTP 429 - POST /api/v1/luma/modify_video ### 回應綱要 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "API key credit limit exceeded" } ``` ## 錯誤 HTTP 409 - POST /api/v1/luma/modify_video ### 回應綱要 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "The request uses features that are not supported for the selected model" } ``` ## 錯誤 HTTP 429 - POST /api/v1/luma/modify_video ### 回應綱要 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "Rate limit reached. Please retry later." } ``` ## 錯誤 HTTP 503 - POST /api/v1/luma/modify_video ### 回應綱要 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "Service under maintenance, please try again later" } ``` ## 錯誤 HTTP 504 - POST /api/v1/luma/modify_video ### 回應綱要 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "The request timed out" } ``` ## 錯誤 HTTP 404 - GET /api/v1/luma/modify_video/:id ### 回應綱要 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "Task with id 'tsk_reference_demo' not found" } ``` ## 產生的程式碼範例 直接使用 cURL，或為您的程式語言安裝 SDK。每個範例均會提交本參考中所示的已驗證請求。 ### curl ```curl curl -X POST https://runapi.ai/api/v1/luma/modify_video \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"model":"luma-modify-video","prompt":"Add a warm golden-hour look.","source_video_url":"https://file.runapi.ai/source-video.mp4"}' ``` ### javascript #### 安裝 ```bash npm install @runapi.ai/luma ``` ```javascript import { LumaClient } from "@runapi.ai/luma"; const client = new LumaClient({ apiKey: process.env.RUNAPI_API_KEY }); const task = await client.modifyVideo.create({ "model": "luma-modify-video", "prompt": "Add a warm golden-hour look.", "source_video_url": "https://file.runapi.ai/source-video.mp4" }); ``` ### python #### 安裝 ```bash pip install runapi-luma ``` ```python import os from runapi.luma import LumaClient client = LumaClient(api_key=os.environ["RUNAPI_API_KEY"]) task = client.modify_video.create( model="luma-modify-video", prompt="Add a warm golden-hour look.", source_video_url="https://file.runapi.ai/source-video.mp4" ) ``` ### go #### 安裝 ```bash go get github.com/runapi-ai/luma-sdk/go@latest ``` ```go package main import ( "context" "log" "os" "github.com/runapi-ai/core-sdk/go/option" luma "github.com/runapi-ai/luma-sdk/go/luma" ) func main() { client, err := luma.NewClient(option.WithAPIKey(os.Getenv("RUNAPI_API_KEY"))) if err != nil { log.Fatal(err) } task, err := client.ModifyVideo.Create(context.Background(), luma.ModifyVideoParams{ Model: "luma-modify-video", Prompt: "Add a warm golden-hour look.", SourceVideoURL: "https://file.runapi.ai/source-video.mp4", }) if err != nil { log.Fatal(err) } _ = task } ``` ### ruby #### 安裝 ```bash gem install runapi-luma ``` ```ruby require "runapi/luma" client = RunApi::Luma::Client.new(api_key: ENV.fetch("RUNAPI_API_KEY")) task = client.modify_video.create( model: "luma-modify-video", prompt: "Add a warm golden-hour look.", source_video_url: "https://file.runapi.ai/source-video.mp4" ) ``` ### java #### 安裝 ```kotlin implementation("ai.runapi:runapi-luma") ``` ```java import ai.runapi.luma.LumaClient; import ai.runapi.luma.types.ModifyVideoParams; import ai.runapi.core.polling.TaskCreateResponse; public final class Example { public static void main(String[] args) { LumaClient client = LumaClient.builder() .apiKey(System.getenv("RUNAPI_API_KEY")) .build(); TaskCreateResponse task = client.modifyVideo().create( ModifyVideoParams.builder() .model("luma-modify-video") .prompt("Add a warm golden-hour look.") .sourceVideoUrl("https://file.runapi.ai/source-video.mp4") .build() ); } } ``` ### php #### 安裝 ```bash composer require runapi-ai/luma ``` ```php modifyVideo->create([ "model" => "luma-modify-video", "prompt" => "Add a warm golden-hour look.", "source_video_url" => "https://file.runapi.ai/source-video.mp4" ]); ``` ## 相關指南 - [身分驗證](https://runapi.ai/zh-TW/docs/guides/authentication.md) - [快速入門](https://runapi.ai/zh-TW/docs/guides/task-api/quickstart.md) --- ## RunAPI 的更多內容 - [首頁](https://runapi.ai/zh-TW/.md) - [模型目錄](https://runapi.ai/zh-TW/models.md) - [價格](https://runapi.ai/zh-TW/pricing.md) - [提供商](https://runapi.ai/zh-TW/models) - [文件](https://runapi.ai/zh-TW/docs/guides) - [SDK](https://runapi.ai/zh-TW/sdk.md) - [CLI](https://runapi.ai/zh-TW/cli.md) - [MCP Server](https://runapi.ai/zh-TW/mcp.md) - [Claude Code 與 Cursor](https://runapi.ai/zh-TW/claude-code-vs-cursor.md) - [Cursor API 設定](https://runapi.ai/zh-TW/cursor-api-setup.md) - [RunAPI 與 OpenRouter](https://runapi.ai/zh-TW/openrouter-alternative.md) - [企業版](https://runapi.ai/zh-TW/contact.md) - [聯絡我們](https://runapi.ai/zh-TW/contact.md) - [服務條款](https://runapi.ai/zh-TW/terms.md) - [隱私權](https://runapi.ai/zh-TW/privacy.md) - [代理程式網站索引](https://runapi.ai/llms.txt) 聯絡我們: contact@runapi.ai ## 結構化資料 ```json [ { "@context": "https://schema.org", "inLanguage": "zh-TW", "@type": "WebSite", "name": "RunAPI", "url": "https://runapi.ai/zh-TW", "potentialAction": { "@type": "SearchAction", "target": { "@type": "EntryPoint", "urlTemplate": "https://runapi.ai/zh-TW/models?q={search_term_string}" }, "query-input": "required name=search_term_string" } }, { "@context": "https://schema.org", "inLanguage": "zh-TW", "@type": "Organization", "name": "RunAPI", "url": "https://runapi.ai/zh-TW", "logo": { "@type": "ImageObject", "url": "https://runapi.ai/zh-TWicon.svg" }, "sameAs": [ "https://github.com/runapi-ai" ] }, { "@context": "https://schema.org", "inLanguage": "zh-TW", "@type": "TechArticle", "headline": "Luma 修改影片", "description": "使用影片修改端點建立非同步 Task。", "url": "https://runapi.ai/zh-TW/docs/api/luma/modify-video", "mainEntityOfPage": "https://runapi.ai/zh-TW/docs/api/luma/modify-video" } ] ```