Skip to main content

​
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

​
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.
1

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.
2

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']}")
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"])
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

OperationCost
Create brand voice50 credits
Use in generationIncluded in generation cost (10–30 credits typically)

​
Best Practices

Include URLs or documents that reflect your desired tone—about page, blog posts, marketing copy. Avoid internal-only or outdated content.
usage_context helps the AI tailor guidelines. E.g. “Marketing and support” vs “Technical documentation.”
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