Documents API

The Documents API is the full pipeline for generating complete, research-backed content with optional images and audio narration.

Pipeline Flow

pending researching generating images audio completed

The audio step only runs when audio.enabled is true.

POST /document/create

Create a new document generation request.

Request Body

Parameter	Type	Required	Description
`prompt`	string	Yes	Topic or instruction for the document (10-5,000 characters)
`model`	string	No	Global model tier: `basic`, `standard` (default), or `advanced`
`content_type`	string	No	`article` (default) or `news`
`keywords`	array	No	SEO keywords to incorporate (max 10)
`text.length`	integer	No	Target word count (100-10000, default: 2000)
`text.formality`	string	No	`formal`, `professional` (default), or `conversational`
`text.voice`	string	No	`neutral` (default), `enthusiastic`, `empathetic`, `authoritative`, `persuasive`, `inspirational`
`text.model`	string	No	Model tier override for text generation: `basic`, `standard`, or `advanced`
`image.enabled`	boolean	No	Generate images (default: `true`)
`image.model`	string	No	Model tier for image generation: `auto` (default), `basic`, `standard`, or `advanced`
`research.model`	string	No	Model tier override for research: `basic`, `standard`, or `advanced`
`audio.enabled`	boolean	No	Enable audio narration (default: `false`)
`audio.model`	string	No	Model tier override for audio: `basic`, `standard`, or `advanced`
`audio.voice`	string	No	TTS voice for narration (default: `Kore`). See Audio API for options.
`audio.language`	string	No	Language code (default: `en-US`)
`audio.format`	string	No	`mp3` (default), `opus`, or `wav`
`audio.style`	string	No	Natural language voice style instructions (max 4,000 chars)
`webhook_url`	string	No	URL to receive completion notification
`site_id`	string	No	Connected site UUID — deliver the completed document to this site
`post_status`	string	No	`draft` (default), `publish`, or `pending`. Requires `site_id`.
`categories`	array	No	Category names for the delivered post. Requires `site_id`.
`tags`	array	No	Tag names for the delivered post. Requires `site_id`.

Example Request

curl -X POST https://api.genrex.io/v1/document/create \
  -H "Authorization: Bearer grx_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Best IoT Projects for College Students in 2025",
    "content_type": "article",
    "keywords": ["IoT", "Arduino", "Raspberry Pi", "college projects"],
    "text": {
      "length": 2000,
      "formality": "professional",
      "voice": "neutral"
    },
    "image": { "enabled": true },
    "audio": { "enabled": true, "voice": "Kore" },
    "webhook_url": "https://yoursite.com/webhooks/genrex",
    "site_id": "550e8400-e29b-41d4-a716-446655440000",
    "post_status": "draft",
    "categories": ["Technology", "IoT"],
    "tags": ["arduino", "esp32"]
  }'

Example Response

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

GET /document/status/{'{uuid}'}

Check the status of a document and retrieve the result when completed.

Path Parameters

Parameter	Type	Description
`uuid`	string	The document UUID returned from create

Status Values

Status	Description
`pending`	Request queued, not yet started
`researching`	Web research in progress
`generating`	Text content being generated
`images`	Images being generated
`audio`	Audio narration being generated (only when `audio.enabled` is `true`)
`completed`	Document ready
`failed`	Generation failed (check error details)

Example Response (Completed)

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "data": {
    "title": "Best IoT Projects for College Students in 2025",
    "description": "Discover the top IoT projects perfect for college students...",
    "featured_image": "https://genrex.io/images/featured/...",
    "content": {
      "type": "document",
      "version": "1.0",
      "meta": {
        "title": "Best IoT Projects for College Students in 2025",
        "slug": "best-iot-projects-for-college-students-in-2025",
        "description": "Discover the top IoT projects...",
        "word_count": 2150,
        "reading_time": "11 min read"
      },
      "featured_image": { ... },
      "content": [ ... ]
    },
    "word_count": 2150,
    "reading_time": "11 min read"
  }
}

Document Content Structure

The content field contains a structured JSON document with the following block types:

Block Type	Description
`heading`	H1-H6 with `level` and `text`
`paragraph`	Array of inline content (text, bold, italic, link, code)
`list`	Ordered/unordered with `items` array
`table`	`headers` and `rows` arrays
`code_block`	`language` and `value`
`image`	`url`, `alt`, `image_type`
`quote`	Blockquote with `value`