Content Generation API

API for generating smart media protocol (SMP) content using AI templates

Overview

Anyone can generate AI content with our APIs - no subscription required.

We use the x402 standard to charge per request via stablecoins (ie USDC on Base Chain).

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

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

  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

ℹ️ Learn how to handle the x402 payment flow here

🤖 Building an agent? Use our ElizaOS plugin

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.

GET /metadata

Response:

{
  "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:

{
  "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.

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

Request Body:

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

Response (402 Payment Required):

{
  "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)

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

Response:

{
  "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.

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):

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

Step 5: Poll for Task Status

Check the generation progress using the returned task ID.

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

Response (Processing):

{
  "status": "processing"
}

Response (Queued):

{
  "status": "queued"
}

Step 6: Get Final Result

When the task is complete, retrieve your generated content.

Response (200 Completed):

{
  "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"
    }
  }
}
PreviousCreating a smart media postNextGeneration

Last updated