> ## Documentation Index > Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a Runway video-to-video task > Use CometAPI Runway POST /runwayml/v1/video_to_video to start video-to-video generation tasks, set X-Runway-Version, and transform source clips. Use this endpoint to transform an existing source clip with Runway's video-to-video workflow. It starts an async task instead of returning the final output immediately. ## Before you call it * Prepare a source video that matches the provider's input requirements * Include the required `X-Runway-Version` header for the feature set you want * Start with one short prompt that describes the change, not a full storyboard ## Output ratio | Setting | Supported values | Default starting point | Boundary behavior | | ------- | -------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------- | | `ratio` | `1280:720`, `720:1280`, or another ratio accepted by the selected Runway model/version | `1280:720` | Match the source clip orientation where possible. | This endpoint expects colon-separated `ratio` values. Use `1280:720` for `1280x720` output and `720:1280` for `720x1280`; `1280x720` is not accepted on every Runway video-to-video route. ## Task flow Start the task from this endpoint and save the returned task id. Use [Get a Runway task](./runway-to-get-task-details) until the task reaches a terminal state. Download or persist the finished asset through your normal media pipeline. ## OpenAPI ````yaml api/openapi/video/runway/official-format/post-generate-a-video-from-a-video.openapi.json POST /runwayml/v1/video_to_video openapi: 3.1.0 info: title: Generate a video from a video API version: 1.0.0 servers: - url: https://api.cometapi.com security: - bearerAuth: [] paths: /runwayml/v1/video_to_video: post: summary: Generate a video from a video operationId: generate_a_video_from_a_video parameters: - name: X-Runway-Version in: header required: true description: Runway API version header, for example `2024-11-06`. schema: type: string requestBody: required: true content: application/json: schema: type: object required: - videoUri - promptText - seed - model - references - ratio - contentModeration properties: videoUri: type: string description: >- HTTPS URL of the source video, or a base64 data URI containing the video. default: https://your-video-host/source.mp4 promptText: type: string description: >- Text prompt describing the desired output. Maximum 1000 characters. default: A cat yawning in slow motion. seed: type: integer description: 'Random seed for reproducible results. Range: 0–4294967295.' default: 1 model: type: string description: Model variant to use. default: gen4_aleph references: type: array description: >- Optional reference images to guide generation. Each item must include `type` (e.g. `image`) and `uri` (HTTPS URL). items: type: object properties: type: type: string uri: type: string default: - {} ratio: type: string description: >- Requested output frame shape. Use colon-separated values such as 1280:720 or 720:1280; read them as 1280x720 and 720x1280 targets. Do not assume every Runway video-to-video route accepts 1280x720 with an x separator. default: '1280:720' contentModeration: type: object required: - publicFigureThreshold properties: publicFigureThreshold: type: string description: >- Threshold for public-figure detection. Use `auto` for default behavior. default: publicFigureThreshold: auto default: videoUri: https://media.w3.org/2010/05/sintel/trailer.mp4 promptText: Make the motion feel cinematic. model: gen4_aleph references: - type: image uri: https://res.cloudinary.com/demo/image/upload/dog.jpg ratio: '1280:720' examples: Default: summary: Default value: videoUri: https://media.w3.org/2010/05/sintel/trailer.mp4 promptText: Make the motion feel cinematic. model: gen4_aleph references: - type: image uri: https://res.cloudinary.com/demo/image/upload/dog.jpg ratio: '1280:720' responses: '200': description: success content: application/json: schema: type: object required: - id properties: id: type: string description: >- The ID of the task that was created. Use this to retrieve the task later. example: id: 12a01a5e-ab55-4aa7-b002-7b873546cf76 x-codeSamples: - lang: Shell label: Default source: | curl https://api.cometapi.com/runwayml/v1/video_to_video \ -H "Authorization: Bearer $COMETAPI_KEY" \ -H "Content-Type: application/json" \ -d '{ "videoUri": "https://your-video-host/source.mp4", "promptText": "Make the motion feel cinematic.", "model": "gen4_aleph", "references": [ { "type": "image", "uri": "https://your-image-host/style.jpg" } ] }' - lang: Python label: Default source: > import os import requests response = requests.post( "https://api.cometapi.com/runwayml/v1/video_to_video", headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]}, json={ "videoUri": "https://your-video-host/source.mp4", "promptText": "Make the motion feel cinematic.", "model": "gen4_aleph", "references": [ { "type": "image", "uri": "https://your-image-host/style.jpg" } ] }, ) task = response.json() print(task["id"]) # poll GET /runwayml/v1/tasks/{id} until the output array appears - lang: JavaScript label: Default source: > const response = await fetch("https://api.cometapi.com/runwayml/v1/video_to_video", { method: "POST", headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "videoUri": "https://your-video-host/source.mp4", "promptText": "Make the motion feel cinematic.", "model": "gen4_aleph", "references": [ { "type": "image", "uri": "https://your-image-host/style.jpg" } ] }), }); const task = await response.json(); console.log(task.id); // poll GET /runwayml/v1/tasks/{id} until the output array appears components: securitySchemes: bearerAuth: type: http scheme: bearer description: Bearer token authentication. Use your CometAPI key. ````