--- title: Hailuo 文字轉影片 | RunAPI description: 使用文字轉影片端點建立非同步 Task。 url: https://runapi.ai/zh-TW/docs/api/hailuo/text-to-video.md canonical: https://runapi.ai/zh-TW/docs/api/hailuo/text-to-video locale: zh-TW --- > HTML 版本: https://runapi.ai/zh-TW/docs/api/hailuo/text-to-video > 代理程式網站索引: https://runapi.ai/llms.txt # Hailuo 文字轉影片 ## 概覽 使用文字轉影片端點搭配支援的模型。使用回傳的 Task ID 擷取其狀態，或提供 callback_url 以接收下方說明的回呼通知。 ### 快速入門 1. 建立 API 金鑰並將其設定為 RUNAPI_API_KEY。 2. 選擇支援的模型，並傳送本文符合該模型結構描述的 POST 請求。 3. 儲存返回的任務 ID，然後輪詢直到終止狀態，或處理下方說明的回呼。 ## 端點 POST /api/v1/hailuo/text_to_video 基礎 URL: https://runapi.ai API 版本: v1 身分驗證: Authorization: Bearer YOUR_API_TOKEN ## 支援的模型 開啟模型頁面以查看目前的定價、速率限制及商業用途詳情。 - [hailuo-02-text-to-video-pro](https://runapi.ai/zh-TW/models/hailuo/02-text-to-video-pro) - [hailuo-02-text-to-video-standard](https://runapi.ai/zh-TW/models/hailuo/02-text-to-video-standard) ## 請求綱要 欄位及允許值取決於所選模型。若提供 callback_url，其將接收下方記錄的 Task 交付內容。 ### hailuo-02-text-to-video-pro ```json { "callback_url": { "type": "string" }, "duration_seconds": { "type": "integer" }, "enable_safety_checker": { "type": "boolean" }, "model": { "type": "string" }, "prompt": { "type": "string" }, "prompt_optimizer": { "type": "boolean" } } ``` ### hailuo-02-text-to-video-standard ```json { "callback_url": { "type": "string" }, "duration_seconds": { "enum": [ 6, 10 ], "type": "integer" }, "enable_safety_checker": { "type": "boolean" }, "model": { "type": "string" }, "prompt": { "type": "string" }, "prompt_optimizer": { "type": "boolean" } } ``` ## 建立接受記錄 HTTP 202 - POST /api/v1/hailuo/text_to_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/hailuo/text_to_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/hailuo/text_to_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": [ "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/hailuo/text_to_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" }, "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/hailuo/text_to_video ### 回應綱要 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "Authentication required" } ``` ## 錯誤 HTTP 401 - GET /api/v1/hailuo/text_to_video/:id ### 回應綱要 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "Authentication required" } ``` ## 錯誤 HTTP 400 - POST /api/v1/hailuo/text_to_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: hailuo-02-text-to-video-pro, hailuo-02-text-to-video-standard" } ``` ## 錯誤 HTTP 402 - POST /api/v1/hailuo/text_to_video ### 回應綱要 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "Insufficient balance" } ``` ## 錯誤 HTTP 429 - POST /api/v1/hailuo/text_to_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/hailuo/text_to_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/hailuo/text_to_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/hailuo/text_to_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/hailuo/text_to_video ### 回應綱要 ```json { "properties": { "error": { "description": "人類可讀的錯誤訊息。", "type": "string" } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### 回應範例 ```json { "error": "The request timed out" } ``` ## 錯誤 HTTP 404 - GET /api/v1/hailuo/text_to_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/hailuo/text_to_video \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"model":"hailuo-02-text-to-video-pro","prompt":"A slow aerial view of a quiet coastline at sunrise."}' ``` ### javascript #### 安裝 ```bash npm install @runapi.ai/hailuo ``` ```javascript import { HailuoClient } from "@runapi.ai/hailuo"; const client = new HailuoClient({ apiKey: process.env.RUNAPI_API_KEY }); const task = await client.textToVideo.create({ "model": "hailuo-02-text-to-video-pro", "prompt": "A slow aerial view of a quiet coastline at sunrise." }); ``` ### python #### 安裝 ```bash pip install runapi-hailuo ``` ```python import os from runapi.hailuo import HailuoClient client = HailuoClient(api_key=os.environ["RUNAPI_API_KEY"]) task = client.text_to_video.create( model="hailuo-02-text-to-video-pro", prompt="A slow aerial view of a quiet coastline at sunrise." ) ``` ### go #### 安裝 ```bash go get github.com/runapi-ai/hailuo-sdk/go@latest ``` ```go package main import ( "context" "log" "os" "github.com/runapi-ai/core-sdk/go/option" hailuo "github.com/runapi-ai/hailuo-sdk/go/hailuo" ) func main() { client, err := hailuo.NewClient(option.WithAPIKey(os.Getenv("RUNAPI_API_KEY"))) if err != nil { log.Fatal(err) } task, err := client.TextToVideo.Create(context.Background(), hailuo.TextToVideoParams{ Model: hailuo.TextToVideoModel("hailuo-02-text-to-video-pro"), Prompt: "A slow aerial view of a quiet coastline at sunrise.", }) if err != nil { log.Fatal(err) } _ = task } ``` ### ruby #### 安裝 ```bash gem install runapi-hailuo ``` ```ruby require "runapi/hailuo" client = RunApi::Hailuo::Client.new(api_key: ENV.fetch("RUNAPI_API_KEY")) task = client.text_to_video.create( model: "hailuo-02-text-to-video-pro", prompt: "A slow aerial view of a quiet coastline at sunrise." ) ``` ### java #### 安裝 ```kotlin implementation("ai.runapi:runapi-hailuo") ``` ```java import ai.runapi.hailuo.HailuoClient; import ai.runapi.hailuo.types.TextToVideoParams; import ai.runapi.core.polling.TaskCreateResponse; public final class Example { public static void main(String[] args) { HailuoClient client = HailuoClient.builder() .apiKey(System.getenv("RUNAPI_API_KEY")) .build(); TaskCreateResponse task = client.textToVideo().create( TextToVideoParams.builder() .model("hailuo-02-text-to-video-pro") .prompt("A slow aerial view of a quiet coastline at sunrise.") .build() ); } } ``` ### php #### 安裝 ```bash composer require runapi-ai/hailuo ``` ```php textToVideo->create([ "model" => "hailuo-02-text-to-video-pro", "prompt" => "A slow aerial view of a quiet coastline at sunrise." ]); ``` ## 相關指南 - [身分驗證](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": "Hailuo 文字轉影片", "description": "使用文字轉影片端點建立非同步 Task。", "url": "https://runapi.ai/zh-TW/docs/api/hailuo/text-to-video", "mainEntityOfPage": "https://runapi.ai/zh-TW/docs/api/hailuo/text-to-video" } ] ```