> ## Documentation Index > Fetch the complete documentation index at: https://docs.gmicloud.ai/llms.txt > Use this file to discover all available pages before exploring further. # wan2.7-r2v > API usage guide for wan2.7-r2v. {/* source_model_id: wan2.7-r2v */} {/* source_updated_at: 1775606113 */} **Model ID** ```bash theme={null} wan2.7-r2v ``` **Calling method:** async # wan2.7-r2v API Usage Guide ## Overview **wan2.7-r2v** generates videos based on reference images and videos, preserving character appearance, object identity, scene layout, and vocal timbre. It supports an optional first frame for joint control and flexible aspect ratios with continuous duration from 2 to 15 seconds. Requests are submitted to the request-queue API and results are retrieved via polling. ## Authentication All API requests require authentication using an API key. Include your API key in the Authorization header: ```bash theme={null} Authorization: Bearer YOUR_API_KEY ``` ## Submit Video Generation Request ### Base URL ``` https://console.gmicloud.ai ``` ### Endpoint ``` POST /api/v1/ie/requestqueue/apikey/requests ``` ### Request Format ```bash theme={null} curl -X POST "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "wan2.7-r2v", "payload": { "prompt": "Video1 holds Image1 and plays a soothing ballad in a coffee shop, while Video2 smiles and walks towards him", "reference_video": [ "https://example.com/role1.mp4", "https://example.com/role2.mp4" ], "reference_image": [ "https://example.com/object.png" ], "negative_prompt": "blurry, low quality, distorted", "resolution": "1080P", "ratio": "16:9", "duration": 10, "prompt_extend": false, "watermark": false, "seed": 12345 } }' ``` ### Request Parameters | Parameter | Type | Required | Description | Default | Constraints | | ----------------- | ------------- | -------- | ------------------------------------------- | ------- | ------------------------------------------------------ | | `prompt` | string | Yes | Text prompt describing desired video | - | Max 1500 characters | | `negative_prompt` | string | No | What to avoid in the video | "" | Max 500 characters | | `first_frame` | image (URL) | No | First frame image for joint control | null | Max 1 image | | `reference_image` | array of URLs | No | Reference images for character/object/scene | \[] | Max 5; images + videos ≤ 5 total | | `reference_video` | array of URLs | No | Reference videos for character/object/voice | \[] | Max 5; images + videos ≤ 5 total | | `resolution` | string (enum) | No | Output resolution tier | "1080P" | Options: `"720P"`, `"1080P"` | | `ratio` | string (enum) | No | Aspect ratio | "16:9" | Options: `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, `"3:4"` | | `duration` | integer | No | Video length in seconds | 5 | 2–15 | | `prompt_extend` | boolean | No | LLM rewrites prompt for richer detail | true | - | | `watermark` | boolean | No | Add fixed `AI Generated` watermark | false | - | | `seed` | integer | No | Random seed for reproducibility | - | 0–2147483647 | ### Response ```json theme={null} { "request_id": "550e8400-e29b-41d4-a716-446655440000", "model": "wan2.7-r2v", "status": "queued", "created_at": 1750442925, "updated_at": 1750442925, "queued_at": 1750442925 } ``` ## Check Request Status ### Endpoint ``` GET /api/v1/ie/requestqueue/apikey/requests/{request_id} ``` ### Example ```bash theme={null} curl -X GET "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests/550e8400-e29b-41d4-a716-446655440000" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Response ```json theme={null} { "request_id": "550e8400-e29b-41d4-a716-446655440000", "org_id": "your-org-id", "model": "wan2.7-r2v", "status": "success", "is_public": false, "payload": { "prompt": "Video1 holds Image1 and plays a soothing ballad in a coffee shop, while Video2 smiles and walks towards him", "reference_video": ["https://example.com/role1.mp4", "https://example.com/role2.mp4"], "reference_image": ["https://example.com/object.png"], "negative_prompt": "blurry, low quality, distorted", "resolution": "1080P", "ratio": "16:9", "duration": 10, "prompt_extend": false, "watermark": false, "seed": 12345 }, "outcome": { "video_url": "https://storage.googleapis.com/bucket/generated-video.mp4", "thumbnail_image_url": "https://storage.googleapis.com/bucket/thumbnail.jpg" }, "created_at": 1750442925, "updated_at": 1750442930, "queued_at": 1750442925 } ``` ## Request Status Values | Status | Description | | ------------ | --------------------------------------- | | `queued` | Request is waiting to be processed | | `processing` | Video generation is in progress | | `success` | Video generation completed successfully | | `failed` | Video generation failed | | `cancelled` | Request was cancelled | ## List Your Requests ### Endpoint ``` GET /api/v1/ie/requestqueue/apikey/requests?model_id=wan2.7-r2v ``` ### Example ```bash theme={null} curl -X GET "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests?model_id=wan2.7-r2v" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## List Available Models ### Endpoint ``` GET /api/v1/apikey/models ``` ### Example ```bash theme={null} curl -X GET "https://console.gmicloud.ai/api/v1/apikey/models" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Tips for Better Results 1. **Reference naming in prompt**: Refer to reference videos as `Video1`, `Video2`, etc. and reference images as `Image1`, `Image2`, etc. in your prompt text 2. **Single character per reference**: Each reference asset used for a character must contain only a single character 3. **Avoid empty-scene videos**: Reference videos should contain the main character, not empty scenes 4. **First frame + references**: Combine a first frame with reference assets for tighter control over the starting composition 5. **Asset limits**: Maximum 1 first frame; at least 1 reference image or video required; total images + videos ≤ 5 6. **Seed for reproducibility**: Fix a seed value to regenerate consistent results