GET /v1/download

Download the generated content for a completed book generation job.

Overview

This endpoint provides a URL for downloading generated content. When accessed, it validates the request and redirects to a fresh signed URL for the file download.

Endpoint

GET https://api.nelliewriter.com/v1/download/{requestId}

Authentication

Not required. This is a public endpoint. Anyone with the requestId can download the file.

💡 Tip: Request IDs are UUIDs and effectively act as temporary passwords, providing security through obscurity.

Path Parameters

Parameter	Type	Description
`requestId`	string	The job ID returned by `POST /v1/book`

Example Requests

cURL

# Download to a file (follow redirects with -L)
curl -L -o my_book.pdf "https://api.nelliewriter.com/v1/download/abcd1234-ef56-7890-abcd-12ef34567890"

Python SDK

from nellie_api import Nellie

client = Nellie(api_key="nel_your_api_key")

# Wait for completion and get result
result = client.books.wait_for_completion("abcd1234-ef56-7890-abcd-12ef34567890")

if result.is_successful():
    # Download the file
    client.books.download(result.request_id, "my_book.pdf")

Python (requests)

import requests

request_id = "abcd1234-ef56-7890-abcd-12ef34567890"
download_url = f"https://api.nelliewriter.com/v1/download/{request_id}"

# Stream download to file (follows redirects automatically)
response = requests.get(download_url, stream=True)
response.raise_for_status()

with open("my_book.pdf", "wb") as f:
    for chunk in response.iter_content(chunk_size=8192):
        f.write(chunk)

print("Download complete!")

JavaScript (Node.js)

const fs = require('fs');
const https = require('https');

const requestId = 'abcd1234-ef56-7890-abcd-12ef34567890';
const downloadUrl = `https://api.nelliewriter.com/v1/download/${requestId}`;

// Note: This follows redirects automatically in most HTTP libraries
const file = fs.createWriteStream('my_book.pdf');
https.get(downloadUrl, (response) => {
  // Handle redirect
  if (response.statusCode === 302) {
    https.get(response.headers.location, (redirectResponse) => {
      redirectResponse.pipe(file);
    });
  } else {
    response.pipe(file);
  }
});

Browser

Simply navigate to the URL or use it in a link:

<a href="https://api.nelliewriter.com/v1/download/abcd1234-ef56-7890-abcd-12ef34567890">
  Download Your Book
</a>

Response

Success (302 Redirect)

On success, the endpoint returns a 302 Found redirect to a signed Google Cloud Storage URL:

HTTP/1.1 302 Found
Location: https://storage.googleapis.com/...?X-Goog-Algorithm=...&X-Goog-Signature=...

The signed URL is valid for 1 hour. If you need to download again after expiration, simply request the download endpoint again; it will generate a fresh signed URL.

Error Responses

Request Not Found (404)

{
  "success": false,
  "error": "Request not found",
  "errorCode": "NOT_FOUND"
}

Request Not Completed (400)

{
  "success": false,
  "error": "Request is not completed (status: processing)",
  "details": "The download is only available after generation completes successfully.",
  "errorCode": "NOT_READY"
}

No Result Available (404)

{
  "success": false,
  "error": "No result available",
  "details": "The generation completed but no output file was produced.",
  "errorCode": "NO_RESULT"
}

Integration with Status Endpoint

The download URL is returned in the resultUrl field of the GET /v1/status response when a job completes:

{
  "requestId": "abcd1234-ef56-7890-abcd-12ef34567890",
  "status": "completed",
  "progress": 100,
  "resultUrl": "https://api.nelliewriter.com/v1/download/abcd1234-ef56-7890-abcd-12ef34567890",
  "creditsUsed": 250
}