> For the complete documentation index, see [llms.txt](https://developer.topazlabs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.topazlabs.com/reference/video/create-request/create-video-request.md).

# Create Video Request

Create a new video enhancement request.

Send information about the video and desired enhancements then receive cost and time estimates.

Calling this endpoint does NOT consume credits.

Calling this endpoint does NOT start processing.

Estimations are based on values provided, and the calculation is rerun once the system receives the source video. If the second estimate is significantly different than the initial values, the request is failed and the credits are fully refunded.

The lower bound value of the cost estimate is billed.

Time estimates are in development and may not be accurate.

Output encoder settings are validated on this endpoint — the accepted `videoEncoder` / `videoProfile` combinations, along with the container, resolution, and bitrate limits of each, are listed under **Supported encoders and profiles** in **OutputInformationVideo**.

### Response body

| **Property**  | **Type** | **Description**                     |
| ------------- | -------- | ----------------------------------- |
| **requestId** | UUID     | Unique request identifier           |
| **estimates** | Object   | Refer to **RequestEstimates** below |

**RequestEstimates**

`cost` and `time` are arrays with two integers each, representing lower and upper bounds of the estimate.

| **Property** | **Type** | **Description**         |
| ------------ | -------- | ----------------------- |
| **cost**     | Array    | Cost range (in credits) |
| **time**     | Array    | Time range (in seconds) |

```json
{"openapi":"3.0.3","info":{"title":"Video API","version":"1.0.0"},"tags":[{"name":"Create Request","description":"This section allows you to create a request and estimate costs\n"}],"servers":[{"url":"https://api.topazlabs.com","description":"Production API base URL"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}},"requestBodies":{"CreateRequest":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["source","filters","output"],"properties":{"source":{"type":"object","description":"Source details for the video","required":["container","size","duration","frameCount","frameRate","resolution"],"properties":{"container":{"type":"string","enum":["3gp","avi","dv","flv","m1v","m2t","m2ts","m2v","m4v","mkv","mov","mp4","mpeg","mpg","mts","mxf","ser","ts","vob","webm","wmv"],"description":"The container format of the video file. Matched case-insensitively."},"size":{"type":"integer","minimum":1,"maximum":100000000000,"exclusiveMaximum":true,"description":"Size of the video file in bytes. Must be under 100 GB."},"duration":{"type":"number","description":"Duration of the video file in seconds"},"frameCount":{"type":"number","description":"Total number of frames in the video"},"frameRate":{"type":"number","description":"Frame rate of the video"},"resolution":{"type":"object","description":"Resolution details of the video","required":["width","height"],"properties":{"width":{"type":"integer","description":"Width of the video in pixels"},"height":{"type":"integer","description":"Height of the video in pixels"}}},"external":{"$ref":"#/components/schemas/ExternalStorage"}}},"filters":{"$ref":"#/components/schemas/InputFilters"},"output":{"$ref":"#/components/schemas/OutputInformationVideo"},"destination":{"type":"object","properties":{"external":{"$ref":"#/components/schemas/ExternalStorage"}}},"notifications":{"type":"object","properties":{"webhookUrl":{"type":"string","description":"Your URL for Topaz Labs to POST webhook notifications to. Webhooks are sent on successful completions and processing failures."}}}}}}}}},"schemas":{"ExternalStorage":{"type":"object","description":"External storage configuration for source or destination files. `provider` is required.\nProvide either `presignedUrl` alone, or all three of `awsCredentials`, `bucketName`, and `key` together for AWS STS AssumeRole-based access.\nFor destinations only, you may instead provide `multipart` with your own pre-signed multi-part upload URLs.\n\nSource access is verified when the request is created: the presigned URL is fetched, or the object is read using the assumed role. A failure here returns a 400.\n","required":["provider"],"oneOf":[{"required":["presignedUrl"]},{"required":["awsCredentials","bucketName","key"]},{"required":["multipart"]}],"properties":{"provider":{"type":"string","enum":["s3"]},"presignedUrl":{"type":"string","description":"Presigned URL to download the source video from or upload the output video to. Provide this alone, or use `awsCredentials`, `bucketName`, and `key` instead."},"awsCredentials":{"description":"AWS STS AssumeRole credentials for accessing the bucket. Required when using `awsCredentials`/`bucketName`/`key` instead of `presignedUrl`.","$ref":"#/components/schemas/CredentialsS3"},"bucketName":{"type":"string","description":"S3 bucket name. Required when using `awsCredentials`/`bucketName`/`key` instead of `presignedUrl`."},"key":{"type":"string","description":"S3 object key. Required when using `awsCredentials`/`bucketName`/`key` instead of `presignedUrl`.\nThe example includes the standard specifier for image sequence requests, with optional directory path. It must begin with \"%\" and end with the integer specifier \"d\". The \"0\" in the example indicates left-padding with zeroes, and \"6\" indicates the number of digits in the file name.\nKeys for video requests must be valid characters supported by S3.\n"},"multipart":{"type":"object","description":"Destination only. Your own pre-signed multi-part upload URLs. These are not validated by Topaz Labs before use.","required":["uploadId","urls"],"properties":{"uploadId":{"type":"string"},"urls":{"type":"array","items":{"type":"string"}}}}}},"CredentialsS3":{"type":"object","required":["roleArn","externalId"],"properties":{"roleArn":{"type":"string","description":"AWS ARN of the role to assume"},"externalId":{"type":"string","description":"Kind of like a secret string for extra layer of security"},"duration":{"type":"integer","minimum":1,"description":"Lifetime of the assumed-role session, in seconds. Defaults to the AWS default when omitted."}}},"InputFilters":{"type":"array","description":"Array of UpscaleFilter or FrameInterpolationFilter objects","items":{"anyOf":[{"$ref":"#/components/schemas/UpscaleFilter"},{"$ref":"#/components/schemas/FrameInterpolationFilter"}]}},"UpscaleFilter":{"title":"Upscale Filter","type":"object","required":["model"],"properties":{"model":{"type":"string","description":"Short code name for the AI model.\n\nNewer models may be accepted before they appear in this list — call `GET /video/status` for the authoritative set of currently supported models.\n","enum":["aaa-9","aaa-10","ahq-12","alq-13","alqs-2","amq-13","amqs-2","ddv-3","dtd-4","dtds-2","dtv-4","dtvs-2","gcg-5","ghq-5","hyp-1","iris-2","iris-3","nxf-1","nxl-1","nyx-3","pnat-1","prob-4","rhea-1","stab-1","thd-3","thf-4","thm-2"]},"videoType":{"type":"string","enum":["Progressive","Interlaced","ProgressiveInterlaced"],"description":"Frame/field type of the video"},"auto":{"type":"string","enum":["Auto","Manual","Relative"],"description":"Parameter mode of the selected model\n- Auto - parameter estimation is used with no customization\n- Relative - uses auto parameters with optional weights added\n- Manual - all parameters are manually set\n"},"fieldOrder":{"type":"string","enum":["TopFirst","BottomFirst","Auto"],"description":"Optional specification of field order for interlaced input videos"},"focusFixLevel":{"type":"string","enum":["None","Normal","Strong"],"description":"Downscales video input for stronger correction of blurred subjects"},"compression":{"type":"number","minimum":-1,"maximum":1,"description":"Adjust strength of compression recovery"},"details":{"type":"number","minimum":-1,"maximum":1,"description":"Amount of detail reconstruction"},"prenoise":{"type":"number","minimum":0,"maximum":0.1,"description":"Adds noise to input to reduce over-smoothing"},"noise":{"type":"number","minimum":-1,"maximum":1,"description":"Amount of noise reduction"},"halo":{"type":"number","minimum":-1,"maximum":1,"description":"Amount of halo reduction"},"preblur":{"type":"number","minimum":-1,"maximum":1,"description":"Adjust anti-aliasing and deblurring strength"},"blur":{"type":"number","minimum":-1,"maximum":1,"description":"Amount of sharpness applied"},"grain":{"type":"number","minimum":0,"maximum":0.1,"description":"Adds grain after AI model processing"},"grainSigma":{"type":"number","minimum":0,"maximum":1,"description":"Grain granularity"},"grainSize":{"type":"number","minimum":0,"maximum":5,"description":"Size of generated grain"},"grainType":{"type":"string","enum":["silver_rich","gaussian","grey"],"description":"Type of grain"},"recoverOriginalDetailValue":{"type":"number","minimum":0,"maximum":1,"description":"Reintroduce source details into the output video"},"transferFunction":{"type":"string","enum":["pq","hlg"],"description":"HDR transfer function. Applies to the Hyperion model (`hyp-1`)."},"adjustExposure":{"type":"number","minimum":0,"maximum":1,"description":"Exposure adjustment. Applies to the Hyperion model (`hyp-1`)."},"boostSaturation":{"type":"number","minimum":0,"maximum":1,"description":"Saturation boost. Applies to the Hyperion model (`hyp-1`)."},"highlightThreshold":{"type":"number","minimum":0.45,"maximum":0.85,"description":"Threshold above which pixels are treated as highlights. Applies to the Hyperion model (`hyp-1`)."},"rollingShutterCorrection":{"type":"boolean","description":"Correct rolling shutter distortion.\n\n__Required when the stabilization model (`stab-1`) is used.__ Omitting it returns a 400.\n"},"strength":{"type":"number","minimum":0,"maximum":16,"description":"Stabilization strength. Applies to the stabilization model (`stab-1`)."},"reduceMotionJitter":{"type":"integer","minimum":0,"maximum":5,"description":"Amount of motion jitter reduction. Applies to the stabilization model (`stab-1`)."},"fullFrame":{"type":"boolean","description":"Preserve the full frame rather than cropping to hide stabilization borders. Applies to the stabilization model (`stab-1`)."}}},"FrameInterpolationFilter":{"title":"Frame Interpolation Filter","type":"object","required":["model"],"properties":{"model":{"type":"string","description":"Short code name for the AI model\n","enum":["aion-1","apf-2","apo-8","chf-3","chr-2"]},"slowmo":{"type":"integer","minimum":1,"maximum":16,"description":"Slow motion factor applied to input video. For example, a value of 2 makes the output twice as slow and doubles the duration."},"fps":{"type":"number","minimum":15,"maximum":240,"description":"Output frame rate, does not increase duration"},"duplicate":{"type":"boolean","description":"Analyze input for duplicate frames and remove them"},"duplicateThreshold":{"type":"number","minimum":0.001,"maximum":0.1,"description":"Sensitivity of detection for duplicate frames"}}},"OutputInformationVideo":{"type":"object","description":"Desired output settings.\n\nSome values are adjusted server-side before processing:\n\n- `resolution` width and height are rounded up to the nearest multiple of 4.\n- `resolution` is forced to the source resolution when no upscale model is present in `filters`.\n- `frameRate` is forced to the source frame rate when no frame interpolation model is present in `filters`, and defaults to it when omitted.\n- With a frame interpolation model, `frameRate` and that filter's `fps` are both set to the greater of the two.\n- `container` is forced to `mov` when `videoEncoder` is `ProRes` and to `mp4` when it is `AV1` or `VP9`, and defaults to `mp4` otherwise.\n\nThe express endpoint supplies no source metadata, so nothing is inferred from the source there: only `resolution` is required, `frameRate` is required only when a frame interpolation filter omits its own `fps`, and the rest of the fields listed as required below take the defaults noted above.\n\n#### Supported encoders and profiles\n\nEvery accepted `videoEncoder` / `videoProfile` pair is listed below. `videoEncoder` defaults to `H265` and `videoProfile` to the default profile of the chosen encoder. Any other combination is rejected with `400` `INVALID_INPUT`, and the error message lists the profiles the encoder does support.\n\n| **videoEncoder** | **videoProfile**     | **container**       | **Max resolution** |\n|------------------|----------------------|---------------------|--------------------|\n| AV1              | `8-bit` _(default)_  | `mp4`               | 16384 x 8704       |\n| AV1              | `10-bit`             | `mp4`               | 16384 x 8704       |\n| H264             | `High` _(default)_   | `mp4`, `mov`, `mkv` | 4096 x 4096        |\n| H265             | `Main`               | `mp4`, `mov`, `mkv` | 8192 x 8192        |\n| H265             | `Main10` _(default)_ | `mp4`, `mov`, `mkv` | 8192 x 8192        |\n| ProRes           | `422 Proxy`          | `mov`               | 16386 x 16386      |\n| ProRes           | `422 LT`             | `mov`               | 16386 x 16386      |\n| ProRes           | `422 Std`            | `mov`               | 16386 x 16386      |\n| ProRes           | `422 HQ` _(default)_ | `mov`               | 16386 x 16386      |\n| VP9              | `Good` _(default)_   | `mp4`               | 8192 x 8192        |\n| VP9              | `Best`               | `mp4`               | 8192 x 8192        |\n\n- Encoder and profile values are matched case-insensitively.\n- **Max resolution** applies in either orientation, so AV1 also accepts 8704 x 16384. Exceeding it is rejected with `400` `INVALID_INPUT`.\n- **container** lists the containers you can receive for that encoder. ProRes, AV1, and VP9 replace whatever `container` you send with the single value shown; H264 and H265 honor your choice among the values shown.\n- `videoBitrate` is capped per encoder — **800 mbps** for AV1, **2000 mbps** for H264, H265, and VP9, and uncapped for ProRes. A higher value is rejected with `400` `INVALID_INPUT` — unless `dynamicCompressionLevel` is also set, in which case `videoBitrate` is discarded and the compression level is used instead.\n- `VP9` requires `videoBitrate`. Selecting it without one is rejected with `400` `INVALID_INPUT`.\n- `dynamicCompressionLevel` maps to a CQP value defined per encoder and profile, and applies to AV1, H264, and H265 only.\n- For ProRes and VP9 the storage portion of the cost estimate is derived from the source file size rather than a predicted output size.\n","required":["resolution","frameRate","audioTransfer"],"properties":{"resolution":{"type":"object","description":"Desired output resolution","required":["width","height"],"properties":{"width":{"type":"integer","description":"Width in pixels. The maximum depends on `videoEncoder` — see **Supported encoders and profiles** above."},"height":{"type":"integer","description":"Height in pixels. The maximum depends on `videoEncoder` — see **Supported encoders and profiles** above."}}},"frameRate":{"type":"number","description":"Frame rate"},"audioBitrate":{"type":"string","description":"Audio bitrate, if audioTransfer is Copy or Convert. Default values for the codec are used if not provided."},"audioCodec":{"type":"string","enum":["AAC","AC3","PCM"],"description":"__Required unless audioTransfer is None.__"},"audioTransfer":{"type":"string","enum":["Copy","Convert","None"]},"videoEncoder":{"type":"string","description":"Video encoder for the output. Defaults to `H265`. See **Supported encoders and profiles** above for the profiles, containers, and limits of each encoder.","enum":["AV1","H264","H265","ProRes","VP9"]},"videoBitrate":{"type":"string","description":"Constant bitrate, suffixed with \"k\" for kilobits or \"m\" for megabits per second. Mutually exclusive with `dynamicCompressionLevel`. __Required when `videoEncoder` is `VP9`.__ Each encoder caps this value — see **Supported encoders and profiles** above."},"dynamicCompressionLevel":{"type":"string","enum":["Low","Mid","High"],"description":"Automatic CQP selection. Mutually exclusive with `videoBitrate`. If neither is provided, this defaults to `High`. Applies to the `AV1`, `H264`, and `H265` encoders only."},"videoProfile":{"type":"string","description":"Codec profile, specific to the chosen `videoEncoder`. Defaults to that encoder's default profile (`Main10` for `H265`). See **Supported encoders and profiles** above for the accepted values."},"cropToFit":{"type":"boolean","description":"Center cropping to fit the output dimensions"},"container":{"type":"string","enum":["mp4","mov","mkv","avi","webm"],"description":"Desired output container. Defaults to `mp4`. Ignored and replaced with `mov` when `videoEncoder` is `ProRes`, and with `mp4` when it is `AV1` or `VP9`."}}},"CreateResponse":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"estimates":{"$ref":"#/components/schemas/RequestEstimates"}}},"RequestEstimates":{"type":"object","description":"Lower and upper bound estimates","properties":{"cost":{"type":"array","description":"In credits","items":{"type":"integer"}},"time":{"type":"array","description":"In seconds, assuming an empty queue, starting from the time the source video has been received","items":{"type":"integer"}}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errorCode":{"type":"string","enum":["INSUFFICIENT_CREDITS","INVALID_INPUT","FORBIDDEN","UNAUTHORIZED","SERVER_MAINTENANCE","SERVER_ERROR","UNKNOWN"]},"errors":{"type":"array","description":"Present when the request failed schema validation. One entry per offending field.","items":{"type":"object","properties":{"type":{"type":"string"},"path":{"type":"string"},"location":{"type":"string"},"msg":{"type":"string"},"value":{}}}}}}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errorCode":{"type":"string","enum":["INSUFFICIENT_CREDITS","INVALID_INPUT","FORBIDDEN","UNAUTHORIZED","SERVER_MAINTENANCE","SERVER_ERROR","UNKNOWN"]}}}}}},"RequestEntityTooLarge":{"description":"The JSON request body exceeds the 3000 byte limit. This response has no body.\n\nLarge bodies are usually caused by long presigned URLs in `source.external` or `destination.external`, or by an unusually large number of filters.\n"},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errorCode":{"type":"string","enum":["INSUFFICIENT_CREDITS","INVALID_INPUT","FORBIDDEN","UNAUTHORIZED","SERVER_MAINTENANCE","SERVER_ERROR","UNKNOWN"]}}}}}},"ServiceUnavailable":{"description":"Service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errorCode":{"type":"string","enum":["INSUFFICIENT_CREDITS","INVALID_INPUT","FORBIDDEN","UNAUTHORIZED","SERVER_MAINTENANCE","SERVER_ERROR","UNKNOWN"]}}}}}}}},"paths":{"/video/":{"post":{"tags":["Create Request"],"summary":"Create Video Request","operationId":"CreateVideoRequest","description":"Create a new video enhancement request.\n\nSend information about the video and desired enhancements then receive cost and time estimates.\n\nCalling this endpoint does NOT consume credits.\n\nCalling this endpoint does NOT start processing.\n\nEstimations are based on values provided, and the calculation is rerun once the system receives the source video. If the second estimate is significantly different than the initial values, the request is failed and the credits are fully refunded.\n\nThe lower bound value of the cost estimate is billed.\n\nTime estimates are in development and may not be accurate.\n\nOutput encoder settings are validated on this endpoint — the accepted `videoEncoder` / `videoProfile` combinations, along with the container, resolution, and bitrate limits of each, are listed under **Supported encoders and profiles** in **OutputInformationVideo**.\n\n## Response body\n\n| **Property**  | **Type** | **Description**                     |\n|---------------|----------|-------------------------------------|\n| **requestId** | UUID     | Unique request identifier           |\n| **estimates** | Object   | Refer to **RequestEstimates** below |\n\n#### RequestEstimates\n\n`cost` and `time` are arrays with two integers each, representing lower and upper bounds of the estimate.\n\n| **Property** | **Type** | **Description**         |\n|--------------|----------|-------------------------|\n| **cost**     | Array    | Cost range (in credits) |\n| **time**     | Array    | Time range (in seconds) |\n","requestBody":{"$ref":"#/components/requestBodies/CreateRequest"},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"413":{"$ref":"#/components/responses/RequestEntityTooLarge"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.topazlabs.com/reference/video/create-request/create-video-request.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.