# Wan 3.0 Reference VIDEOFeaturedalibaba-wan-3-0-reference **Wan 3.0 Reference** is the reference-guided mode of [Alibaba’s](https://huggingface.co/Wan-AI) Wan 3.0 video model. It accepts up to 10 reference images, 5 video clips, and 5 audio files alongside a text prompt, enabling multi-modal control over style, character consistency, motion, and sound for clips up to 30 seconds at 480p, 720p, or 1080p. Reference media can be addressed positionally in the prompt (e.g. Image 1, Video 1), making it ideal for brand-consistent series and multi-shot production. Best for Multi-reference character and style lock across long clips, Guiding motion from reference video and audio, Up to 10 images + 5 videos + 5 audio refs POST /v2/workspaces/{workspace\_id}/base-models/alibaba-wan-3-0-reference/inferences ```bash curl --request POST \ --url https://api.app.layer.ai/api/v2/workspaces/:workspace_id/base-models/alibaba-wan-3-0-reference/inferences \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "a knight standing in a snowy forest", "aspect_ratio": "LANDSCAPE_16_9_1080p", "duration_seconds": 2, "generate_audio": false, "guidance_file_first_frame": [ { "url": "" } ], "guidance_file_reference_image": [ { "url": "" } ], "guidance_file_reference_video": [ { "url": "" } ], "guidance_file_reference_audio": [ { "url": "" } ] }' ``` ```python import requests url = "https://api.app.layer.ai/api/v2/workspaces/:workspace_id/base-models/alibaba-wan-3-0-reference/inferences" payload = { "prompt": "a knight standing in a snowy forest", "aspect_ratio": "LANDSCAPE_16_9_1080p", "duration_seconds": 2, "generate_audio": False, "guidance_file_first_frame": [{ "url": "" }], "guidance_file_reference_image": [{ "url": "" }], "guidance_file_reference_video": [{ "url": "" }], "guidance_file_reference_audio": [{ "url": "" }] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```js const url = 'https://api.app.layer.ai/api/v2/workspaces/:workspace_id/base-models/alibaba-wan-3-0-reference/inferences'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"prompt":"a knight standing in a snowy forest","aspect_ratio":"LANDSCAPE_16_9_1080p","duration_seconds":2,"generate_audio":false,"guidance_file_first_frame":[{"url":""}],"guidance_file_reference_image":[{"url":""}],"guidance_file_reference_video":[{"url":""}],"guidance_file_reference_audio":[{"url":""}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.app.layer.ai/api/v2/workspaces/:workspace_id/base-models/alibaba-wan-3-0-reference/inferences" payload := strings.NewReader("{\n \"prompt\": \"a knight standing in a snowy forest\",\n \"aspect_ratio\": \"LANDSCAPE_16_9_1080p\",\n \"duration_seconds\": 2,\n \"generate_audio\": false,\n \"guidance_file_first_frame\": [\n {\n \"url\": \"\"\n }\n ],\n \"guidance_file_reference_image\": [\n {\n \"url\": \"\"\n }\n ],\n \"guidance_file_reference_video\": [\n {\n \"url\": \"\"\n }\n ],\n \"guidance_file_reference_audio\": [\n {\n \"url\": \"\"\n }\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```php "https://api.app.layer.ai/api/v2/workspaces/:workspace_id/base-models/alibaba-wan-3-0-reference/inferences", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => json_encode([ 'prompt' => 'a knight standing in a snowy forest', 'aspect_ratio' => 'LANDSCAPE_16_9_1080p', 'duration_seconds' => 2, 'generate_audio' => null, 'guidance_file_first_frame' => [ [ 'url' => '' ] ], 'guidance_file_reference_image' => [ [ 'url' => '' ] ], 'guidance_file_reference_video' => [ [ 'url' => '' ] ], 'guidance_file_reference_audio' => [ [ 'url' => '' ] ] ]), CURLOPT_HTTPHEADER => [ "Authorization: Bearer ", "Content-Type: application/json" ], ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } ``` ```java OkHttpClient client = new OkHttpClient(); MediaType mediaType = MediaType.parse("application/json"); RequestBody body = RequestBody.create(mediaType, "{\n \"prompt\": \"a knight standing in a snowy forest\",\n \"aspect_ratio\": \"LANDSCAPE_16_9_1080p\",\n \"duration_seconds\": 2,\n \"generate_audio\": false,\n \"guidance_file_first_frame\": [\n {\n \"url\": \"\"\n }\n ],\n \"guidance_file_reference_image\": [\n {\n \"url\": \"\"\n }\n ],\n \"guidance_file_reference_video\": [\n {\n \"url\": \"\"\n }\n ],\n \"guidance_file_reference_audio\": [\n {\n \"url\": \"\"\n }\n ]\n}"); Request request = new Request.Builder() .url("https://api.app.layer.ai/api/v2/workspaces/:workspace_id/base-models/alibaba-wan-3-0-reference/inferences") .post(body) .addHeader("Authorization", "Bearer ") .addHeader("Content-Type", "application/json") .build(); Response response = client.newCall(request).execute(); ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.app.layer.ai/api/v2/workspaces/:workspace_id/base-models/alibaba-wan-3-0-reference/inferences") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"prompt\": \"a knight standing in a snowy forest\",\n \"aspect_ratio\": \"LANDSCAPE_16_9_1080p\",\n \"duration_seconds\": 2,\n \"generate_audio\": false,\n \"guidance_file_first_frame\": [\n {\n \"url\": \"\"\n }\n ],\n \"guidance_file_reference_image\": [\n {\n \"url\": \"\"\n }\n ],\n \"guidance_file_reference_video\": [\n {\n \"url\": \"\"\n }\n ],\n \"guidance_file_reference_audio\": [\n {\n \"url\": \"\"\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```csharp var client = new RestClient("https://api.app.layer.ai/api/v2/workspaces/:workspace_id/base-models/alibaba-wan-3-0-reference/inferences"); var request = new RestRequest("", Method.Post); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"prompt\": \"a knight standing in a snowy forest\",\n \"aspect_ratio\": \"LANDSCAPE_16_9_1080p\",\n \"duration_seconds\": 2,\n \"generate_audio\": false,\n \"guidance_file_first_frame\": [\n {\n \"url\": \"\"\n }\n ],\n \"guidance_file_reference_image\": [\n {\n \"url\": \"\"\n }\n ],\n \"guidance_file_reference_video\": [\n {\n \"url\": \"\"\n }\n ],\n \"guidance_file_reference_audio\": [\n {\n \"url\": \"\"\n }\n ]\n}", ParameterType.RequestBody); var response = client.Execute(request); ``` * Production ## Authorizations * **[bearerAuth](/docs/v2/rest-api#bearerauth)** ## Parameters ### Path Parameters **workspace\_id** required _Workspace Id_ Id of the workspace that owns the resource. string format: uuid Id of the workspace that owns the resource. ### Query Parameters **session\_name** Any of: **string** string **null** null Organize this run under a named session. A new session is created if none matches. ## Request Bodyrequired _Wan 3.0 Reference_object **prompt** _Prompt_ string "" **aspect\_ratio** _Aspect Ratio_ string default: LANDSCAPE\_16\_9\_1080p Allowed values: LANDSCAPE\_16\_9\_1080p PORTRAIT\_9\_16\_1080p LANDSCAPE\_4\_3\_1080p PORTRAIT\_3\_4\_1080p SQUARE\_1080p LANDSCAPE\_16\_9\_720p PORTRAIT\_9\_16\_720p LANDSCAPE\_4\_3\_720p PORTRAIT\_3\_4\_720p SQUARE\_720p LANDSCAPE\_16\_9\_480p PORTRAIT\_9\_16\_480p LANDSCAPE\_4\_3\_480p PORTRAIT\_3\_4\_480p SQUARE\_480p **seed** _Seed_ _Advanced field._ integer nullable **duration\_seconds** _Duration_ integer default: 2 **generate\_audio** _Generate Audio_ boolean **guidance\_file\_first\_frame** _First frame_ The frame the video starts on Array _InferenceFormFileRef_ A single guidance/reference file supplied to a `reference_image_list` field. The slot’s guidance `type` is fixed by the field it’s attached to; the caller supplies the file URL and, where the model supports per-file weighting, a weight. object **url** required _Url_ string **weight** _Weight_ number nullable **guidance\_file\_reference\_image** _Reference image_ Guides style and content without being modified Array _InferenceFormFileRef_ A single guidance/reference file supplied to a `reference_image_list` field. The slot’s guidance `type` is fixed by the field it’s attached to; the caller supplies the file URL and, where the model supports per-file weighting, a weight. object **url** required _Url_ string **weight** _Weight_ number nullable **guidance\_file\_reference\_video** _Reference video_ Guides style and motion without being modified Array _InferenceFormFileRef_ A single guidance/reference file supplied to a `reference_image_list` field. The slot’s guidance `type` is fixed by the field it’s attached to; the caller supplies the file URL and, where the model supports per-file weighting, a weight. object **url** required _Url_ string **weight** _Weight_ number nullable **guidance\_file\_reference\_audio** _Reference audio_ Guides style and voice without being modified Array _InferenceFormFileRef_ A single guidance/reference file supplied to a `reference_image_list` field. The slot’s guidance `type` is fixed by the field it’s attached to; the caller supplies the file URL and, where the model supports per-file weighting, a weight. object **url** required _Url_ string **weight** _Weight_ number nullable **prompt\_language** _Prompt Language_ _Advanced field._ string nullable ##### Example ```json { "prompt": "a knight standing in a snowy forest", "aspect_ratio": "LANDSCAPE_16_9_1080p", "duration_seconds": 2, "generate_audio": false, "guidance_file_first_frame": [ { "url": "" } ], "guidance_file_reference_image": [ { "url": "" } ], "guidance_file_reference_video": [ { "url": "" } ], "guidance_file_reference_audio": [ { "url": "" } ] } ``` ## Responses ### 202 Successful Response _ExecuteForgeOutput_object **inference\_id** required _Inference Id_ Unique identifier for this forge run. string format: uuid **status** required _InferenceStatus_ Current status: IN\_PROGRESS. string Allowed values: in\_progress complete failed cancelled deleted **estimated\_price\_creative\_units** Any of: **number** number **null** null **poll\_interval\_seconds** required _Poll Interval Seconds_ Suggested polling interval in seconds. integer **created\_at** required _Created At_ Timestamp of when the run was created. string format: date-time **session\_id** Any of: **string** string format: uuid **null** null **normalized\_parameters** Any of: **NormalizedInferenceParameters** _NormalizedInferenceParameters_ Inference parameters after model-specific normalization. These reflect the actual values used for generation, including model defaults applied for any parameters not explicitly set. object **width** Any of: **null** integer **integer** null **height** Any of: **null** integer **integer** null **batch\_size** Any of: **null** integer **integer** null **num\_inference\_steps** Any of: **null** integer **integer** null **guidance\_scale** Any of: **null** number **number** null **duration\_seconds** Any of: **null** number **number** null **fps** Any of: **null** integer **integer** null **null** null ##### Example ```json { "status": "in_progress" } ``` ### 401 Unauthenticated — missing or invalid Bearer token. object **type** required string **title** required string **status** required integer **detail** required string ##### Example ```json { "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description." } ``` ### 403 Forbidden — insufficient permissions. object **type** required string **title** required string **status** required integer **detail** required string ##### Example ```json { "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description." } ``` ### 404 Resource not found. object **type** required string **title** required string **status** required integer **detail** required string ##### Example ```json { "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description." } ``` ### 422 Invalid input parameters. object **type** required string **title** required string **status** required integer **detail** required string ##### Example ```json { "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description." } ``` ### 429 Rate limited — too many concurrent requests. object **type** required string **title** required string **status** required integer **detail** required string ##### Example ```json { "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description." } ``` ### 500 Internal server error. object **type** required string **title** required string **status** required integer **detail** required string ##### Example ```json { "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description." } ```