> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavera.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Brand Voice

> AI-powered brand voice profiles for consistent 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](/features/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:

<CodeGroup>
  ```python Python theme={"dark"}
  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
  ```

  ```javascript JavaScript theme={"dark"}
  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);
  ```
</CodeGroup>

### From Documents (Uploaded Files)

For internal documents (PDFs, Word, etc.), upload them via the [Files API](/features/files) 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`.

<Steps>
  <Step title="Upload documents">
    Use the Files API presigned flow: `POST /files/upload-url` → `PUT` to upload → `POST /files` to create records. See [Files & Folders](/features/files) for the full flow.
  </Step>

  <Step title="Create brand voice with documents">
    Pass a `documents` array with `{ name, url, file_type, file_size }` for each uploaded file.
  </Step>
</Steps>

<CodeGroup>
  ```python Python theme={"dark"}
  # 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']}")
  ```

  ```javascript JavaScript theme={"dark"}
  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",
    }),
  });
  ```
</CodeGroup>

<Info>
  You can combine `urls` and `documents` in the same request. Brand voice creation costs **50 credits** per profile.
</Info>

## Brand Voice Profile

Once processed, a brand voice includes:

```json theme={"dark"}
{
  "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.

```python theme={"dark"}
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.

<CodeGroup>
  ```python Python theme={"dark"}
  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"])
  ```

  ```javascript JavaScript theme={"dark"}
  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);
  ```
</CodeGroup>

<Info>
  For templates and `input_data` structure, see [Content Generation](/features/content-generation). List generation apps with `GET /generation-apps` to see available templates and their required input fields.
</Info>

## List Brand Voices

```bash theme={"dark"}
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.

```python theme={"dark"}
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

<AccordionGroup>
  <Accordion title="Use representative samples">
    Include URLs or documents that reflect your desired tone—about page, blog posts, marketing copy. Avoid internal-only or outdated content.
  </Accordion>

  <Accordion title="Specify usage_context">
    `usage_context` helps the AI tailor guidelines. E.g. "Marketing and support" vs "Technical documentation."
  </Accordion>

  <Accordion title="Reuse across generations">
    Create once, use many times. Brand voice profiles are stored and can be applied to all compatible generation apps.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Content Generation" icon="wand-magic-sparkles" href="/features/content-generation">
    Use brand voice in blog posts and more
  </Card>

  <Card title="Files API" icon="cloud-arrow-up" href="/features/files">
    Upload documents for brand voice
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/brand-voice/create-a-brand-voice">
    Full API specification
  </Card>
</CardGroup>