Content Generation

Overview

The Generations API creates AI-powered content using pre-built templates with optional brand voice styling. Generate blog posts, social media content, email campaigns, product descriptions, and more. Each template has specific input_data fields—list generation apps to discover available templates and their parameters.

Typical Flow

List generation apps

Call GET /generation-apps to see available templates, their app_id, descriptions, and required input_data fields.

Create a generation

Call POST /generations with app_id, input_data (template-specific), optional brand_voice_id, and workspace_id. Some apps return immediately; others may run asynchronously (poll or use webhook if supported).

Read the output

Response includes output (text) and often markdown. Check usage.credits_used for cost.

Available Templates

Browse generation apps to find templates and their input structure:

import requests

response = requests.get(
    "https://app.mavera.io/api/v1/generation-apps",
    headers={"Authorization": "Bearer mvra_live_your_key_here"}
)

data = response.json()
if "error" in data:
    raise Exception(data["error"]["message"])

apps = data["data"]
for app in apps:
    print(f"{app['id']}: {app.get('name', app['id'])}")
    print(f"  Description: {app.get('description', '')[:80]}...")
    print(f"  Input schema: {app.get('input_schema', app.get('input_data', {}))}")

const resp = await fetch("https://app.mavera.io/api/v1/generation-apps", {
  headers: { Authorization: "Bearer mvra_live_your_key_here" },
});
const { data: apps } = await resp.json();
apps.forEach((app) => {
  console.log(app.id, app.name || app.id);
  console.log("  Input:", app.input_schema || app.input_data);
});

Creating Content

Pass app_id (from generation apps), input_data (fields required by that template), optional brand_voice_id, and workspace_id.

response = requests.post(
    "https://app.mavera.io/api/v1/generations",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    json={
        "app_id": "blog_post_generator",
        "title": "Q1 Product Launch Blog",
        "brand_voice_id": "bv_abc123",  # Optional — apply brand voice
        "input_data": {
            "topic": "New Product Features",
            "target_audience": "Small business owners",
            "tone": "professional yet approachable",
            "length": "1000 words"
        },
        "workspace_id": "your_workspace_id"
    }
)

generation = response.json()
if "error" in generation:
    raise Exception(generation["error"]["message"])

print(f"Content:\n{generation['output']}")
print(f"Credits used: {generation.get('usage', {}).get('credits_used')}")

const resp = await fetch("https://app.mavera.io/api/v1/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer mvra_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    app_id: "blog_post_generator",
    title: "Q1 Product Launch Blog",
    brand_voice_id: "bv_abc123",
    input_data: {
      topic: "New Product Features",
      target_audience: "Small business owners",
      tone: "professional yet approachable",
      length: "1000 words",
    },
    workspace_id: "your_workspace_id",
  }),
});
const gen = await resp.json();
console.log(gen.output);
console.log("Credits:", gen.usage?.credits_used);

Common input_data Fields

Different templates expect different fields. Typical examples:

Field	Example	Description
`topic`	”Product launch”	Main subject
`target_audience`	”SMB owners”	Who it’s for
`tone`	”professional, friendly”	Writing tone
`length`	”500 words”	Desired length
`key_points`	[“Feature A”, “Pricing”]	Bullet points to include
`platform`	”LinkedIn”	For social templates

Check GET /generation-apps for the exact schema per template.

Response Format

{
  "id": "gen_abc123",
  "title": "Q1 Product Launch Blog",
  "app": "blog_post_generator",
  "output": "# Introducing Our Latest Features\n\nWe're excited to announce...",
  "markdown": "# Introducing Our Latest Features...",
  "content_type": "MARKDOWN",
  "status": "COMPLETED",
  "usage": {
    "credits_used": 15
  }
}

If the generation runs asynchronously, status may be PENDING or RUNNING. Poll GET /generations/{id} until status is COMPLETED.

Polling for Completion (Async Generations)

Some templates process asynchronously. Poll until status is COMPLETED:

import time

def wait_for_generation(gen_id, max_wait_minutes=5):
    for _ in range(max_wait_minutes * 6):
        resp = requests.get(
            f"https://app.mavera.io/api/v1/generations/{gen_id}",
            headers={"Authorization": "Bearer mvra_live_your_key_here"}
        )
        data = resp.json()
        if data.get("status") == "COMPLETED":
            return data
        time.sleep(10)
    raise TimeoutError("Generation did not complete")

List Generations

curl https://app.mavera.io/api/v1/generations \
  -H "Authorization: Bearer mvra_live_your_key_here"

Optionally filter by workspace_id, app_id, or paginate with cursor and limit.

Delete a Generation

curl -X DELETE https://app.mavera.io/api/v1/generations/gen_abc123 \
  -H "Authorization: Bearer mvra_live_your_key_here"

Credit Costs

Operation	Typical Cost
Create generation	10–30 credits
Depends on template, output length	Longer content = more credits

Check usage.credits_used in each response. See Credits for your plan.

Best Practices

Use brand voice for consistency

Pass brand_voice_id from a Brand Voice profile so output matches your tone and vocabulary.

Be specific in input_data

Clear topic, target_audience, and key_points produce better output than vague prompts.

List apps first

Call GET /generation-apps to discover templates and required fields before building your integration.

Brand Voice

Create and use brand voice profiles

Credits

Credit allocation and tracking

API Reference

Full API specification

Getting Started

Core Concepts

Features

SDKs & Libraries

Content Generation

Overview

Typical Flow

Available Templates

Creating Content

Common input_data Fields

Response Format

Polling for Completion (Async Generations)

List Generations

Delete a Generation

Credit Costs

Best Practices

Brand Voice

Credits

API Reference

​Overview

​Typical Flow

​Available Templates

​Creating Content

​Common input_data Fields

​Response Format

​Polling for Completion (Async Generations)

​List Generations

​Delete a Generation

​Credit Costs

​Best Practices

Brand Voice

Credits

API Reference

Overview

Typical Flow

Available Templates

Creating Content

Common input_data Fields

Response Format

Polling for Completion (Async Generations)

List Generations

Delete a Generation

Credit Costs

Best Practices