AI Writer API¶

Generate marketing copy, blog posts, social media content, and more using 30+ AI templates.

Base URL: https://api.vell.ai/api/v1 Authentication: Bearer token Prefix: /aiwriter

Endpoints¶

List Available Templates¶

GET /aiwriter/openai-list

Returns all text generation templates available to the authenticated user. Premium templates require an active subscription with a premium-tier plan.

Response:

[
  {
    "id": 1,
    "title": "Blog Post Generator",
    "description": "Generate SEO-optimized blog posts",
    "slug": "post_generator",
    "type": "text",
    "premium": false
  }
]

Get Template Details¶

GET /aiwriter/generator/{slug}

Parameter	Type	Location	Description
`slug`	string	path	Template slug (e.g., `blog_intros`)

Response:

{
  "openai": {
    "id": 1,
    "title": "Blog Intros",
    "slug": "blog_intros",
    "description": "Generate compelling blog introductions",
    "type": "text",
    "questions": "[{\"name\":\"title\"},{\"name\":\"description\"}]"
  },
  "userOpenai": []
}

Generate Content (Two-Step Flow)¶

Content generation uses a two-step process: first create the output record, then stream the result.

Step 1: Build Output¶

POST /aiwriter/generate

Common Parameters:

Parameter	Type	Required	Default	Description
`post_type`	string	Yes	—	Template slug (see table below)
`maximum_length`	integer	No	Site default	Maximum word/token count
`number_of_results`	integer	No	`1`	Number of outputs to generate
`creativity`	number	No	Site default	Temperature (0–1)
`language`	string	No	—	Language code (e.g., `en-US`)
`tone_of_voice`	string	No	Site default	Tone preset
`tone_of_voice_custom`	string	No	—	Custom tone (overrides preset)
`company`	integer	No	—	Company ID for brand voice
`product`	integer	No	—	Product ID

Template-Specific Parameters:

Template (`post_type`)	Required Fields
`post_generator`	`description`
`article_generator`	`article_title`, `focus_keywords`
`blog_intros`	`title`, `description`
`blog_conclusion`	`title`, `description`
`blog_post_ideas`	`description`
`blog_section`	`description`
`summarize_text`	`text_to_summary`
`content_rewrite`	`contents`
`paragraph_generator`	`description`, `keywords`
`product_description`	`product_name`, `description`
`product_name`	`seed_words`, `product_description`
`facebook_ads`	`title`, `description`
`google_ads_headlines`	`product_name`, `description`, `audience`
`google_ads_description`	`product_name`, `description`, `audience`
`instagram_captions`	`title`
`instagram_hashtag`	`keywords`
`youtube_video_title`	`description`
`youtube_video_description`	`title`
`youtube_video_tag`	`title`
`social_media_post_tweet`	`title`
`email_generator`	`subject`, `description`
`newsletter_generator`	`description`, `subject`, `title`
`meta_description`	`title`, `description`, `keywords`
`faq_generator`	`title`, `description`
`ai_code_generator`	`description`, `code_language`

Response:

{
  "message_id": 456,
  "creativity": 0.75,
  "maximum_length": 200,
  "number_of_results": 1,
  "inputPrompt": "Write a blog intro about..."
}

Important

This endpoint returns a message_id, not the generated text. Use Step 2 to stream the actual output.

Step 2: Stream Output¶

POST /aiwriter/generate-output

Parameter	Type	Required	Description
`message_id`	integer	Yes	From Step 1 response
`creativity`	number	Yes	Temperature (0–1)
`maximum_length`	integer	Yes	Max tokens
`number_of_results`	integer	Yes	Number of results

Response: text/event-stream (SSE)

data: # Blog Introduction
data:
data: Cloud cost optimization is
data:  one of the most impactful
data:  strategies for modern enterprises...
data: [DONE]

Python

import requests

API = "https://api.vell.ai/api/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}

# Step 1: Create output record
resp = requests.post(f"{API}/aiwriter/generate", headers=HEADERS, json={
    "post_type": "blog_intros",
    "title": "Cloud Cost Optimization",
    "description": "How to reduce AWS spend by 40%",
    "creativity": 0.7,
    "maximum_length": 300,
    "number_of_results": 1,
})
msg = resp.json()

# Step 2: Stream the result
stream = requests.post(f"{API}/aiwriter/generate-output", headers=HEADERS, json={
    "message_id": msg["message_id"],
    "creativity": 0.7,
    "maximum_length": 300,
    "number_of_results": 1,
}, stream=True)

for line in stream.iter_lines():
    text = line.decode()
    if text.startswith("data: ") and text != "data: [DONE]":
        print(text[6:], end="")

Save Generated Output¶

POST /aiwriter/generate/save

Parameter	Type	Required	Description
`message_id`	integer	Yes	Output record ID
`response`	string	Yes	Generated text to save

Response:

{ "status": "Data saved successfully." }

Favorites¶

List Favorites¶

GET /aiwriter/favorite-openai-list

Returns an array of favorited template IDs: [1, 5, 12]

Add to Favorites¶

POST /aiwriter/favorite-openai-list-add

Parameter	Type	Required	Description
`openai_id`	integer	Yes	Template ID to favorite

Remove from Favorites¶

POST /aiwriter/favorite-openai-list-remove

Parameter	Type	Required	Description
`openai_id`	integer	Yes	Template ID to unfavorite

Use Cases¶

Generate a Blog Post Series¶

List templates with GET /aiwriter/openai-list to find blog_post_ideas
Generate 5 blog title ideas with post_type: "blog_post_ideas"
For each title, generate an intro (blog_intros), body sections (blog_section), and conclusion (blog_conclusion)
Use a consistent company ID to maintain brand voice across all posts

Create Multi-Channel Campaign Copy¶

Start with a product description: post_type: "product_description"
Reuse the description for social: facebook_ads, instagram_captions, social_media_post_tweet
Generate email copy: email_generator, newsletter_generator
Add SEO: meta_description with target keywords

Automate Content Pipelines¶

Combine the AI Writer with the Content Workflow API to:

Generate content via POST /aiwriter/generate + stream
Push to the kanban board via POST /content-workflow/kanban/{id}/status
Set up workflow triggers to auto-generate content on schedule