POST /v1/book

Start an asynchronous book generation job.

Overview

This endpoint starts a new book generation request. The job runs asynchronously; you’ll receive a requestId immediately that you can use to poll for status or receive results via webhook.

Endpoint

POST https://api.nelliewriter.com/v1/book

Authentication

Required. Include your API key in the X-API-Key header.

X-API-Key: nel_your_api_key_here

Request Headers

Request Body

All parameters are optional. If you send an empty body {}, Nellie will generate a unique book with default settings.

Parameter Details

prompt

The core idea for your book. Can range from a single word to a detailed synopsis.

// One Word
{"prompt": "Rebellion"}

// Simple
{"prompt": "A crime mystery set in 1920s Paris"}

// Detailed
{"prompt": "A sci-fi thriller about a Mars colony that discovers alien ruins. The protagonist is a geologist named Dr. Sarah Chen. Include themes of isolation and first contact."}

If omitted, Nellie generates a unique creative prompt automatically.

style

Genre or narrative style. Valid values:

type

The format and structure of the output:

images

Set to true to generate context-relevant AI illustrations or photorealistic portraits throughout the book. Increases generation time.

{"images": true}

author

The name that appears as the author in the generated book.

{"author": "Jessica Walker"}

custom_tone

Additional guidance for the writing style of the text itself.

{"custom_tone": "Write like Shakespeare"}

model

output_format

File format for the generated book:

webhook_url

HTTPS URL that Nellie will POST to when the job completes or fails:

{"webhook_url": "https://your-site.com/api/nellie-webhook"}

Requirements:

• Must be a valid HTTPS URL
• Must be publicly accessible
• Cannot be localhost or internal IPs (SSRF protection)

See Webhooks for payload details.

Example Requests

Minimal Request

curl -X POST https://api.nelliewriter.com/v1/book \
  -H "X-API-Key: nel_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'

Full Request

curl -X POST https://api.nelliewriter.com/v1/book \
  -H "X-API-Key: nel_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A noir detective story in 1940s Los Angeles",
    "style": "noir",
    "type": "novel",
    "images": true,
    "author": "Ray Hamilton",
    "custom_tone": "First-person narration, cynical wit, atmospheric descriptions",
    "model": "3.0",
    "output_format": "epub",
    "webhook_url": "https://myapp.com/webhooks/nellie"
  }'

Python SDK

from nellie_api import Nellie

client = Nellie(api_key="nel_your_api_key")

book = client.books.create(
    prompt="A noir detective story in 1940s Los Angeles",
    style="noir",
    type="novel",
    images=True,
    author="Ray Hamilton",
    custom_tone="First-person narration, cynical wit",
    model="3.0",
    output_format="epub",
    webhook_url="https://myapp.com/webhooks/nellie"
)

print(f"Job started: {book.request_id}")

Response

Success (202 Accepted)

{
  "success": true,
  "requestId": "abcd1234-ef56-7890-abcd-12ef34567890",
  "status": "queued",
  "statusUrl": "https://api.nelliewriter.com/v1/status/abcd1234-ef56-7890-abcd-12ef34567890",
  "message": "Job queued successfully"
}

Error Responses

400 Bad Request: Invalid Parameter

{
  "success": false,
  "error": "Field 'style' must be one of: action, adventure, automatic, ...",
  "errorCode": "INVALID_PARAMETER"
}

400 Bad Request: Invalid Webhook URL

{
  "success": false,
  "error": "Invalid webhook URL: must be a valid HTTPS URL",
  "errorCode": "INVALID_WEBHOOK_URL"
}

401 Unauthorized

{
  "success": false,
  "error": "Unauthorized",
  "details": "Valid API key required",
  "errorCode": "AUTH_REQUIRED"
}

429 Too Many Requests

{
  "success": false,
  "error": "Rate limit exceeded: Please wait a few seconds between requests",
  "errorCode": "RATE_LIMIT_EXCEEDED"
}

429 Daily Limit Exceeded

{
  "success": false,
  "error": "Daily rate limit exceeded (15 requests/day)",
  "errorCode": "RATE_LIMIT_EXCEEDED"
}

What Happens Next

After a successful response:

1. Job is queued: Your request enters the generation queue (usually there is no wait, and it will start within minutes)
2. Processing begins: Nellie generates your book (15-80 minutes typical)
3. Completion: Either:
   • Poll GET /v1/status/{requestId} to check progress
   • Receive a webhook POST if you provided webhook_url

Rate Limits

• Minimum spacing: 6 seconds between requests
• Daily limit: 15 requests per API key (contact us for increased limits)

See Rate Limits for details.

Credits

Generation costs credits based on:

Credits are deducted upon successful completion. Failed jobs don’t consume credits. If a failed job consumes credits please contact us.

Related Endpoints

• GET /v1/status/{requestId}: Check job progress
• GET /v1/configuration: List valid parameter values
• GET /v1/models: List available models and costs
• GET /v1/usage: Check your credit balance

See Also

• Quick Start Guide
• Webhooks
• Python SDK