Skip to main content
View Categories

POST /v1/book

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 #

Header Required Description
X-API-Key Yes Your Nellie API key
Content-Type Yes Must be application/json

Request Body #

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

Parameter Type Default Description
prompt string Auto-generated Your book idea, synopsis, or detailed instructions
style string "automatic" Genre or narrative style
type string "automatic" Book structure
images boolean false Generate AI illustrations
author string "Nellie" Author name for attribution
custom_tone string " Unique writing style guidance
model string "2.0" Nellie AI model version
output_format string "txt" File format for export
webhook_url string null URL to notify on completion

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:

Value Description
automatic Let Nellie choose based on prompt
action Fast-paced action sequences
adventure Exploration and journey
alternate_history Historical “what if” scenarios
comedy Humor and lighthearted tone
crime Criminal investigations
cyberpunk High-tech, low-life futures
drama Character-driven emotional stories
dystopian Oppressive future societies
epic Grand scale narratives
fable Moral tales with allegory
fairy_tale Magical traditional stories
fantasy Magic and mythical worlds
folklore Traditional cultural stories
gothic Dark, atmospheric horror
history Historical settings
horror Fear and suspense
legend Heroic traditional tales
mystery Puzzles and detective work
mythology Ancient myths retold
noir Dark, cynical crime
paranormal Supernatural elements
post_apocalyptic After civilization falls
psychological Mind and perception
romance Love stories
sci_fi Science fiction
superhero Powers and heroism
surrealism Dreamlike, absurd
suspense Tension and anticipation
thriller High-stakes danger
tragedy Downfall narratives
western American frontier

type #

The format and structure of the output:

Value Description
automatic Let Nellie choose
novel Full-length fiction
short_story Brief narrative
comic Illustrated comic format
manga Japanese-style comic
childrens Children’s book
non_fiction Factual content
textbook Educational material
self_help Personal development

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 #

Value Name Credits Description
"2.0" Nellie 2.0 (Standard) 250 Balanced speed and quality
"3.0" Nellie 3.0 (Premium) 500 Higher creativity and coherence

output_format #

File format for the generated book:

Value Description
txt Plain text
pdf PDF document
epub E-book format
md Markdown
html Web page
json Structured JSON data

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"
}
Field Type Description
success boolean Always true for successful requests
requestId string Unique job identifier (UUID)
status string Initial status, always "queued"
statusUrl string Full URL to poll for status
message string Human-readable confirmation

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:

Factor Impact
Model 2.0 ~250 credits
Model 3.0 ~500 credits

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

Related Endpoints #