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

# Content Generation

> AI-powered content creation with templates

## Overview

The Generations API creates AI-powered content using pre-built templates with optional [brand voice](/features/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

<Steps>
  <Step title="List generation apps">
    Call `GET /generation-apps` to see available templates, their `app_id`, descriptions, and required `input_data` fields.
  </Step>

  <Step title="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).
  </Step>

  <Step title="Read the output">
    Response includes `output` (text) and often `markdown`. Check `usage.credits_used` for cost.
  </Step>
</Steps>

## Available Templates

Browse generation apps to find templates and their input structure:

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

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

## Creating Content

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

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

  ```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",
      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);
  ```
</CodeGroup>

### 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

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

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

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

```bash theme={"dark"}
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](/guides/credits) for your plan.

## Best Practices

<AccordionGroup>
  <Accordion title="Use brand voice for consistency">
    Pass `brand_voice_id` from a [Brand Voice](/features/brand-voice) profile so output matches your tone and vocabulary.
  </Accordion>

  <Accordion title="Be specific in input_data">
    Clear `topic`, `target_audience`, and `key_points` produce better output than vague prompts.
  </Accordion>

  <Accordion title="List apps first">
    Call `GET /generation-apps` to discover templates and required fields before building your integration.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Brand Voice" icon="bullhorn" href="/features/brand-voice">
    Create and use brand voice profiles
  </Card>

  <Card title="Credits" icon="coins" href="/guides/credits">
    Credit allocation and tracking
  </Card>

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