Brand Voice

Overview

Brand Voice API lets you create and manage brand voice profiles that ensure consistent tone across all AI-generated content. Upload URLs and documents, and AI generates tone guidelines, vocabulary preferences, and writing style recommendations. Use brand voice in Content Generation to style blog posts, emails, and social content.

Creating a Brand Voice

From URLs

Pass public URLs (e.g. your website pages, blog posts) for the AI to analyze:

import requests

response = requests.post(
    "https://app.mavera.io/api/v1/brand-voices",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    json={
        "label": "Main Brand Voice",
        "usage_context": "Marketing content and customer communications",
        "urls": [
            "https://yourbrand.com/about",
            "https://yourbrand.com/blog"
        ],
        "workspace_id": "your_workspace_id"
    }
)

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

print(f"Brand Voice ID: {brand_voice['id']}")
print(f"Status: {brand_voice['status']}")  # PENDING → READY when processed

const resp = await fetch("https://app.mavera.io/api/v1/brand-voices", {
  method: "POST",
  headers: {
    Authorization: "Bearer mvra_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Main Brand Voice",
    usage_context: "Marketing content",
    urls: ["https://yourbrand.com/about", "https://yourbrand.com/blog"],
    workspace_id: "your_workspace_id",
  }),
});
const brandVoice = await resp.json();
console.log("ID:", brandVoice.id, "Status:", brandVoice.status);

From Documents (Uploaded Files)

For internal documents (PDFs, Word, etc.), upload them via the Files API first, then pass the file metadata to brand voice creation. Each document should have name, url (the public URL from the upload), file_type, and file_size.

Upload documents

Use the Files API presigned flow: POST /files/upload-url → PUT to upload → POST /files to create records. See Files & Folders for the full flow.

Create brand voice with documents

Pass a documents array with { name, url, file_type, file_size } for each uploaded file.

# Assume you have uploaded files and have their metadata
uploaded_files = [
    {"name": "brand_guidelines.pdf", "url": "https://...", "file_type": "application/pdf", "file_size": 125000},
    {"name": "blog_samples.docx", "url": "https://...", "file_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "file_size": 45000},
]

response = requests.post(
    "https://app.mavera.io/api/v1/brand-voices",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    json={
        "label": "Brand Voice from Docs",
        "usage_context": "Marketing and support content",
        "documents": uploaded_files,
        "workspace_id": "your_workspace_id"
    }
)

brand_voice = response.json()
print(f"ID: {brand_voice['id']} | Status: {brand_voice['status']}")

const uploadedFiles = [
  { name: "brand_guidelines.pdf", url: "https://...", file_type: "application/pdf", file_size: 125000 },
];

const resp = await fetch("https://app.mavera.io/api/v1/brand-voices", {
  method: "POST",
  headers: {
    Authorization: "Bearer mvra_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Brand Voice from Docs",
    usage_context: "Marketing content",
    documents: uploadedFiles,
    workspace_id: "your_workspace_id",
  }),
});

You can combine urls and documents in the same request. Brand voice creation costs 50 credits per profile.

Brand Voice Profile

Once processed, a brand voice includes:

{
  "id": "bv_abc123",
  "label": "Main Brand Voice",
  "status": "READY",
  "voice_summary": "Confident yet approachable, with a focus on empowering customers...",
  "tone_adjectives": ["confident", "friendly", "innovative", "trustworthy"],
  "tone_dos": [
    "Use active voice",
    "Address the reader directly",
    "Include concrete examples"
  ],
  "tone_donts": [
    "Avoid jargon",
    "Don't be overly formal",
    "Never use passive aggressive language"
  ],
  "preferred_terms": ["customers", "solutions", "empower"],
  "avoid_terms": ["users", "problems", "cheap"],
  "sentence_structure": "Mix of short punchy sentences and longer explanatory ones"
}

Polling for READY Status

Brand voice creation is asynchronous. Poll GET /brand-voices/{id} until status is READY before using it in generations.

import time

def wait_for_brand_voice(bv_id, max_wait_minutes=5):
    for _ in range(max_wait_minutes * 6):
        resp = requests.get(
            f"https://app.mavera.io/api/v1/brand-voices/{bv_id}",
            headers={"Authorization": "Bearer mvra_live_your_key_here"}
        )
        data = resp.json()
        if data.get("status") == "READY":
            return data
        time.sleep(10)
    raise TimeoutError("Brand voice did not become READY")

Using Brand Voice in Content Generation

Pass brand_voice_id when creating content. The generated output will follow the profile’s tone, vocabulary, and style.

response = requests.post(
    "https://app.mavera.io/api/v1/generations",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    json={
        "app_id": "blog_post_generator",
        "brand_voice_id": "bv_abc123",
        "input_data": {
            "topic": "Product Launch Announcement",
            "key_points": ["New features", "Pricing", "Availability"]
        },
        "workspace_id": "your_workspace_id"
    }
)

generation = response.json()
print(generation["output"])

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",
    brand_voice_id: "bv_abc123",
    input_data: { topic: "Product Launch", key_points: ["Features", "Pricing"] },
    workspace_id: "your_workspace_id",
  }),
});
const gen = await resp.json();
console.log(gen.output);

For templates and input_data structure, see Content Generation. List generation apps with GET /generation-apps to see available templates and their required input fields.

List Brand Voices

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

Set Default Brand Voice

Set a brand voice as the default for your workspace so generations use it when no brand_voice_id is specified.

response = requests.patch(
    f"https://app.mavera.io/api/v1/brand-voices/{brand_voice_id}",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    json={"is_default": True}
)

Credit Costs

Operation	Cost
Create brand voice	50 credits
Use in generation	Included in generation cost (10–30 credits typically)

Best Practices

Use representative samples

Include URLs or documents that reflect your desired tone—about page, blog posts, marketing copy. Avoid internal-only or outdated content.

Specify usage_context

usage_context helps the AI tailor guidelines. E.g. “Marketing and support” vs “Technical documentation.”

Reuse across generations

Create once, use many times. Brand voice profiles are stored and can be applied to all compatible generation apps.

Content Generation

Use brand voice in blog posts and more

Files API

Upload documents for brand voice

API Reference

Full API specification

Getting Started

Core Concepts

Features

SDKs & Libraries

Overview

Creating a Brand Voice

From URLs

From Documents (Uploaded Files)

Brand Voice Profile

Polling for READY Status

Using Brand Voice in Content Generation

List Brand Voices

Set Default Brand Voice

Credit Costs

Best Practices

Content Generation

Files API

API Reference

​Overview

​Creating a Brand Voice

​From URLs

​From Documents (Uploaded Files)

​Brand Voice Profile

​Polling for READY Status

​Using Brand Voice in Content Generation

​List Brand Voices

​Set Default Brand Voice

​Credit Costs

​Best Practices

Content Generation

Files API

API Reference

Overview

Creating a Brand Voice

From URLs

From Documents (Uploaded Files)

Brand Voice Profile

Polling for READY Status

Using Brand Voice in Content Generation

List Brand Voices

Set Default Brand Voice

Credit Costs

Best Practices