> For the documentation index, fetch https://sync.so/docs/llms.txt. Append .md to a page URL for Markdown. Documentation-search MCP: https://sync.so/docs/_mcp/server.

# Get Generation Download URL

GET https://api.sync.so/v2/generations/{id}/download

Obtain the available full output of a completed generation in your
organization. Authenticate with `x-api-key`; no Studio project or user
session is required. Any valid API key belonging to the generation's
organization can request the URL.

The successful response is an **unquoted URL in a text/plain body**,
not JSON, a redirect, or the video itself. Fetch that URL separately
without forwarding your API key.

```bash
download_url=$(curl --fail-with-body --silent --show-error \
  -H "x-api-key: $SYNC_API_KEY" \
  "https://api.sync.so/v2/generations/$GENERATION_ID/download") &&
curl --fail --location "$download_url" --output output.mov
```

The URL resolves an existing output using your organization's current
plan and billing-version eligibility. Free and watermark-required plans
receive the watermarked derivative when present. Entitled plans (such
as v2 Creator and v3 Starter or higher) receive the clean output when
available. Historical outputs can have the watermark burned in, so an
upgrade does not guarantee every old output becomes watermark-free.
Outputs created without a watermark can remain clean after a downgrade.
If no watermarked derivative exists, the resolver retains its existing
fallback to the original output; changing plans does not rewrite files.
This endpoint does not generate a new render or remove burned-in watermarks.

Signed S3 URLs request seven-day validity, but credential expiry,
revocation, access changes, or file deletion can make them unusable
sooner. Request this endpoint again for a fresh signed URL while the
output is still available. The selected S3 file is checked before
signing; a successful response does not guarantee future availability.
Older URL-only records return their stored URL unchanged, without
checking its availability or extending its original expiration.
These URLs are download credentials: keep them private.

Errors use the standard JSON error body and stable `errorCode`:

| Status | Code | Meaning / next step |
| --- | --- | --- |
| 400 | — | Invalid generation UUID. |
| 401 | — | API key missing, invalid, or revoked. |
| 404 | `generation_not_found` | Missing, deleted, or outside your organization. |
| 404 | `generation_output_unavailable` | No eligible output reference or the selected file is missing; contact support. |
| 409 | `generation_not_ready` | Pending or processing; poll Get Generation until COMPLETED. |
| 422 | `generation_not_downloadable` | Failed or rejected; inspect the generation error. |
| 503 | `generation_download_unavailable` | Storage lookup or signing failed; retry with backoff. |

Authentication also returns 422 for draft organizations. Requesting a
download URL does not create a project, incur a generation charge, or
restore deleted files.

Reference: https://sync.so/docs/api-reference/api/generate-api/download

## Authentication

- `x-api-key` header (required) — API Key authentication via header

## Servers

- `https://api.sync.so` (Default, default)
- `https://dev-api.sync.so` (dev)
- `http://localhost:3001` (local)

## Request

### Path parameters

- `id` (string, required) — A unique identifier for the generation.

### Query parameters

- `fileName` (string, optional) — Optional download filename. Its extension is replaced with the output's format. Ignored for URL-only outputs.

### Headers

- `x-sync-accelerate` (string, optional) — Send true to request transfer acceleration; falls back to the standard endpoint when acceleration is disabled.

## Response

### 200

Unquoted download URL. Read as text and fetch separately.

## Errors

### 400 Bad Request Error

Bad Request - Invalid input or unsupported model

- `message` (GenerationErrorMessage, required) — A message describing the error.
- `statusCode` (double, required) — The type of error that occurred.
- `errorCode` (string, optional) — Stable, machine-readable error code (e.g. project_not_found, voice_not_found, concurrency_limit_reached). Branch your error handling on this, not on the message text. The full catalog of codes with messages and suggested fixes is served unauthenticated at GET /v2/errors.
- `suggestion` (string, optional) — A suggested fix an agent can act on.
- `field` (string, optional) — The request field the error refers to, when the failure is tied to a specific field (e.g. projectId, voiceId, input[].assetId).
- `docsUrl` (string, optional) — Link to the documentation page for the failing operation.
- `requestId` (string, optional) — Present on unexpected 500 responses. Include it when contacting support so the failing request can be located directly.
- `generationId` (string, optional) — Original generation ID when available for an uncertain keyed submission. Poll this ID; do not create another action to bypass IDEMPOTENCY_OUTCOME_UNKNOWN.
- `dialogueEditSection` (DialogueEditRetimeFailureSection, optional) — For dialogue_edit_removal_too_large: the section to change, when it can be identified. Create a new dialogue edit preview before submitting again.

### 401 Unauthorized Error

Unauthorized - Invalid or missing authentication

- `message` (GenerationErrorMessage, required) — A message describing the error.
- `statusCode` (double, required) — The type of error that occurred.
- `errorCode` (string, optional) — Stable, machine-readable error code (e.g. project_not_found, voice_not_found, concurrency_limit_reached). Branch your error handling on this, not on the message text. The full catalog of codes with messages and suggested fixes is served unauthenticated at GET /v2/errors.
- `suggestion` (string, optional) — A suggested fix an agent can act on.
- `field` (string, optional) — The request field the error refers to, when the failure is tied to a specific field (e.g. projectId, voiceId, input[].assetId).
- `docsUrl` (string, optional) — Link to the documentation page for the failing operation.
- `requestId` (string, optional) — Present on unexpected 500 responses. Include it when contacting support so the failing request can be located directly.
- `generationId` (string, optional) — Original generation ID when available for an uncertain keyed submission. Poll this ID; do not create another action to bypass IDEMPOTENCY_OUTCOME_UNKNOWN.
- `dialogueEditSection` (DialogueEditRetimeFailureSection, optional) — For dialogue_edit_removal_too_large: the section to change, when it can be identified. Create a new dialogue edit preview before submitting again.

### 404 Not Found Error

Job not found

- `message` (GenerationErrorMessage, required) — A message describing the error.
- `statusCode` (double, required) — The type of error that occurred.
- `errorCode` (string, optional) — Stable, machine-readable error code (e.g. project_not_found, voice_not_found, concurrency_limit_reached). Branch your error handling on this, not on the message text. The full catalog of codes with messages and suggested fixes is served unauthenticated at GET /v2/errors.
- `suggestion` (string, optional) — A suggested fix an agent can act on.
- `field` (string, optional) — The request field the error refers to, when the failure is tied to a specific field (e.g. projectId, voiceId, input[].assetId).
- `docsUrl` (string, optional) — Link to the documentation page for the failing operation.
- `requestId` (string, optional) — Present on unexpected 500 responses. Include it when contacting support so the failing request can be located directly.
- `generationId` (string, optional) — Original generation ID when available for an uncertain keyed submission. Poll this ID; do not create another action to bypass IDEMPOTENCY_OUTCOME_UNKNOWN.
- `dialogueEditSection` (DialogueEditRetimeFailureSection, optional) — For dialogue_edit_removal_too_large: the section to change, when it can be identified. Create a new dialogue edit preview before submitting again.

### 409 Conflict Error

Conflict - The resource is in a state that does not allow the requested action (e.g. deleting a generation that is still processing). For creation, generation_conflict indicates a duplicate internal backend submission. Keyed creates return IDEMPOTENCY_KEY_CONFLICT for a changed payload or IDEMPOTENCY_IN_PROGRESS while the original request prepares (Retry-After: 2). Retry only with the same key and original inputs after an ambiguous network failure. See [Idempotent Requests](/api-reference/guides/idempotency).

- `message` (GenerationErrorMessage, required) — A message describing the error.
- `statusCode` (double, required) — The type of error that occurred.
- `errorCode` (string, optional) — Stable, machine-readable error code (e.g. project_not_found, voice_not_found, concurrency_limit_reached). Branch your error handling on this, not on the message text. The full catalog of codes with messages and suggested fixes is served unauthenticated at GET /v2/errors.
- `suggestion` (string, optional) — A suggested fix an agent can act on.
- `field` (string, optional) — The request field the error refers to, when the failure is tied to a specific field (e.g. projectId, voiceId, input[].assetId).
- `docsUrl` (string, optional) — Link to the documentation page for the failing operation.
- `requestId` (string, optional) — Present on unexpected 500 responses. Include it when contacting support so the failing request can be located directly.
- `generationId` (string, optional) — Original generation ID when available for an uncertain keyed submission. Poll this ID; do not create another action to bypass IDEMPOTENCY_OUTCOME_UNKNOWN.
- `dialogueEditSection` (DialogueEditRetimeFailureSection, optional) — For dialogue_edit_removal_too_large: the section to change, when it can be identified. Create a new dialogue edit preview before submitting again.

### 422 Unprocessable Entity Error

Unprocessable Entity - The requested generation is not downloadable (generation_not_downloadable), or submit-time validation failed (e.g. inaccessible media, invalid segments, a projectId/voiceId/assetId that does not resolve in your organization, or a file exceeding the plan size limit). The body carries a stable errorCode and, where applicable, the failing field.

- `message` (GenerationErrorMessage, required) — A message describing the error.
- `statusCode` (double, required) — The type of error that occurred.
- `errorCode` (string, optional) — Stable, machine-readable error code (e.g. project_not_found, voice_not_found, concurrency_limit_reached). Branch your error handling on this, not on the message text. The full catalog of codes with messages and suggested fixes is served unauthenticated at GET /v2/errors.
- `suggestion` (string, optional) — A suggested fix an agent can act on.
- `field` (string, optional) — The request field the error refers to, when the failure is tied to a specific field (e.g. projectId, voiceId, input[].assetId).
- `docsUrl` (string, optional) — Link to the documentation page for the failing operation.
- `requestId` (string, optional) — Present on unexpected 500 responses. Include it when contacting support so the failing request can be located directly.
- `generationId` (string, optional) — Original generation ID when available for an uncertain keyed submission. Poll this ID; do not create another action to bypass IDEMPOTENCY_OUTCOME_UNKNOWN.
- `dialogueEditSection` (DialogueEditRetimeFailureSection, optional) — For dialogue_edit_removal_too_large: the section to change, when it can be identified. Create a new dialogue edit preview before submitting again.

### 503 Service Unavailable Error

Service Unavailable - A sync. labs service or provider dependency is temporarily unavailable. The body carries a stable errorCode such as elevenlabs_service_unavailable or controller_dependency_error. Keyed generation creates may return IDEMPOTENCY_OUTCOME_UNKNOWN when acceptance needs reconciliation, or IDEMPOTENCY_UNAVAILABLE when new keyed admission is disabled. Preserve the same key and payload; do not bypass protection. generation_admission_paused means new generation requests are paused for maintenance; generation_admission_unavailable means the API can't confirm it is accepting them. Retry after Retry-After.

- `message` (GenerationErrorMessage, required) — A message describing the error.
- `statusCode` (double, required) — The type of error that occurred.
- `errorCode` (string, optional) — Stable, machine-readable error code (e.g. project_not_found, voice_not_found, concurrency_limit_reached). Branch your error handling on this, not on the message text. The full catalog of codes with messages and suggested fixes is served unauthenticated at GET /v2/errors.
- `suggestion` (string, optional) — A suggested fix an agent can act on.
- `field` (string, optional) — The request field the error refers to, when the failure is tied to a specific field (e.g. projectId, voiceId, input[].assetId).
- `docsUrl` (string, optional) — Link to the documentation page for the failing operation.
- `requestId` (string, optional) — Present on unexpected 500 responses. Include it when contacting support so the failing request can be located directly.
- `generationId` (string, optional) — Original generation ID when available for an uncertain keyed submission. Poll this ID; do not create another action to bypass IDEMPOTENCY_OUTCOME_UNKNOWN.
- `dialogueEditSection` (DialogueEditRetimeFailureSection, optional) — For dialogue_edit_removal_too_large: the section to change, when it can be identified. Create a new dialogue edit preview before submitting again.

## Types

### GenerationErrorMessage

A message describing the error.

### DialogueEditRetimeFailureSection

The dialogue-edit section that removes too much speech to stay in sync.

- `slotIndex` (integer, required) — Zero-based index of the section in the preview's `resultSlots`.
- `sourceStartMs` (integer, optional) — Start of the section in the source video, in absolute milliseconds.
- `sourceDurationMs` (integer, optional) — Length of the section in the source video, in milliseconds.

## Examples

**Response**

```json
"string"
```

**SDK Code**

```python
import requests

url = "https://api.sync.so/v2/generations/id/download"

headers = {"x-api-key": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.sync.so/v2/generations/id/download';
const options = {method: 'GET', headers: {'x-api-key': '<apiKey>'}};

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"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sync.so/v2/generations/id/download"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.sync.so/v2/generations/id/download")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.sync.so/v2/generations/id/download")
  .header("x-api-key", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.sync.so/v2/generations/id/download', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.sync.so/v2/generations/id/download");
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["x-api-key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sync.so/v2/generations/id/download")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```