# Content Generation API

## Overview

Anyone can generate AI content with our APIs - no subscription required.&#x20;

We use the [x402 standard](https://x402.org/) to charge per request via stablecoins (ie USDC on Base Chain).&#x20;

The following models are used for generations - based on generation template type

* `video`: [Veo 3](https://cloud.google.com/vertex-ai/generative-ai/docs/models/veo/3-0-generate-preview), [Veo Fast](https://cloud.google.com/vertex-ai/generative-ai/docs/models/veo/3-0-fast-generate-preview), [Hailuai](https://hailuoai.video/)
* `image`: [Venice](https://venice.ai/)&#x20;
* `text`: [Venice](https://venice.ai/)

## Features

We expose the following capabilities through our API

* fetching metadata on templates
* enhancing a prompt based on specific prompt guidelines
* requesting an image generation (with our without a subtemplate)
* requesting a video generation (with our without a subtemplate)

## Request Flow

1. Generation request is submitted to `/generation/create` with payload `{ prompt, template }`
2. The server estimates the cost based on `template` and `prompt` and responds with HTTP status code `402 PAYMENT REQUIRED`&#x20;
3. The sender completes the onchain payment and submits the request again with the payment headers
4. The server verifies the payment, submits the generation request, and returns HTTP status code `202 ACCEPTED` and response body with `taskId`
5. The sender can poll using `generation/status` and `taskId` where the generation result is returned

## :information\_source: Learn how to handle the x402 payment flow [here](https://x402.gitbook.io/x402/getting-started/quickstart-for-buyers)

## :robot: Building an agent? Use our [ElizaOS plugin](https://onbonsai.gitbook.io/docs/elizaos/plugin-bonsai)

## Guide

This guide demonstrates the typical workflow for generating AI content using the Bonsai API.

Check out our open source package to see the full code examples: <https://github.com/onbonsai/plugin-bonsai/blob/main/src/services/generation.ts#L140>

### Base URL

```
https://eliza.onbons.ai
```

### Step 1: Get Server Metadata

Discover available templates, costs, and configuration.

```http
GET /metadata
```

**Response:**

```json
{
  "domain": "https://eliza.onbons.ai",
  "version": "1.2.3",
  "templates": [
    {
      "name": "video",
      "description": "Generate AI-powered videos with narration",
      "category": "video",
      "estimatedCost": 0.05,
      "templateData": {
        "form": {
          "sceneDescription": "string",
          "narration": "string",
          "stylePreset": "string",
          "elevenLabsVoiceId": "string"
        }
      }
    }
  ],
  "acl": {
    "address": "0x742d35Cc6634C0532925a3b8D67684Cb4e0d1234",
    "chainId": 137
  }
}
```

### Step 2: Choose Template & Prepare Data

Based on the metadata, select a template (e.g., "video") and prepare your template data according to the form schema.

**Example Template Data:**

```json
{
  "sceneDescription": "A futuristic character waves in a neon cyberpunk city",
  "forceVideoModel": "veo fast",
}
```

### Step 3: Optional - Enhance Your Prompt

Improve your prompt for better generation quality.

```http
POST /generation/enhance
Content-Type: application/json
```

**Request Body:**

```json
{
  "prompt": "A futuristic character waves in a neon cyberpunk city",
  "template": "video",
  "templateData": { /* your template data */ }
}
```

**Response (402 Payment Required):**

```json
{
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "5000",
      "resource": "http://eliza.onbons.ai/generation/enhance",
      "description": "Enhance prompt for template: video",
      "mimeType": "",
      "payTo": "0x21aF1185734D213D45C6236146fb81E2b0E8b821",
      "maxTimeoutSeconds": 60,
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ]
}
```

**(with X-PAYMENT header)**

```http
Content-Type: application/json
X-PAYMENT: <x402-payment-proof>
```

**Response:**

```json
{
  "enhancedPrompt": "A futuristic character with glowing cybernetic enhancements waves enthusiastically at the camera in a neon-lit cyberpunk cityscape with holographic advertisements and flying cars in the background"
}
```

### Step 4: Create Generation Request

Submit your generation request with x402 payment handling.

```http
POST /generation/create
Content-Type: multipart/form-data
```

**Form Data:**

```
template: "video"
prompt: "A futuristic character waves in a neon cyberpunk city"
templateData: '{"sceneDescription":"A futuristic character...","narration":"Hello, Bonsai!"}'
seed: "my-unique-seed" (optional)
image: [binary file] (optional)
```

**Response (with X-PAYMENT header):**

```json
{
  "taskId": "123e4567-e89b-12d3-a456-426614174000"
}
```

### Step 5: Poll for Task Status

Check the generation progress using the returned task ID.

```http
GET /generation/123e4567-e89b-12d3-a456-426614174000/status
```

**Response (Processing):**

```json
{
  "status": "processing"
}
```

**Response (Queued):**

```json
{
  "status": "queued"
}
```

### Step 6: Get Final Result

When the task is complete, retrieve your generated content.

**Response (200 Completed):**

```json
{
  "status": "completed",
  "result": {
    "generation": {
      "text": "Generated description text",
      "image": "https://storj.onbons.ai/preview-image-url",
      "video": {
        "url": "https://storj.onbons.ai/generated-video-url"
      },
      "templateName": "video",
      "agentId": "agent-uuid"
    },
    "templateData": {
      "sceneDescription": "A futuristic character waves...",
      "narration": "Hello, Bonsai!",
      "stylePreset": "Cinematic"
    }
  }
}
```
