> For the complete documentation index, see [llms.txt](https://imagineclub.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://imagineclub.gitbook.io/docs/generation/content-generation-api.md).

# Content Generation API

## Overview

Generate AIGC (ai generated content) using the most advanced video models and optionally coin them to earn trading fees.

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

## Request Flow

1. Generation request is submitted to `/generation/create`               
2. The server estimates the cost based on the payload 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

## :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](/docs/elizaos/plugin-imagine.md)

## Guide

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

### Resource URL

```
POST https://eliza.getimagine.club/generation/create
```

### Step 1: Create Generation Request

Submit your generation request with x402 payment handling.

```http
POST https://eliza.getimagine.club/generation/create
Content-Type: application/json
```

**Example body**

```json
{
  "prompt": "A futuristic character waves in a neon cyberpunk city",
  "templateData": {
    "videoModel": "sora",
    "duration": 8,
    "image": "https://example.com/input_reference.jpg",
    "autoClank": false,
    "autoEnhance": false
  }
}
```

**Response (402 Payment Required):**

```json
{
    "x402Version": 1,
    "error": "X-PAYMENT header is required",
    "accepts": [
        {
            "scheme": "exact",
            "network": "base",
            "maxAmountRequired": "1000000",
            "resource": "https://eliza.getimagine.club/generation/create",
            "description": "Generate AIGC (ai generated content) using the most advanced video models and optionally coin them to earn trading fees",
            "mimeType": "",
            "payTo": "0x13a9e3ee4A25C3C72D67F42044438aabc54f2b96",
            "maxTimeoutSeconds": 60,
            "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
            "outputSchema": {
                "input": {
                    "type": "http",
                    "method": "POST",
                    "mimeType": "application/json",
                    "discoverable": true,
                    "bodyType": "json",
                    "bodyFields": {
                        "prompt": {
                            "type": "string",
                            "description": "Text prompt describing the video to generate",
                            "required": true
                        },
                        "templateData": {
                            "type": "string",
                            "description": "JSON stringified object with optional configuration. Include 'image' property here for image-to-video generation.",
                            "required": false,
                            "properties": {
                                "videoModel": {
                                    "type": "string",
                                    "enum": [
                                        "sora"
                                    ],
                                    "default": "sora",
                                    "description": "Video generation model to use"
                                },
                                "soraVideoId": {
                                    "type": "string",
                                    "description": "Sora video ID for remix/continuation"
                                },
                                "duration": {
                                    "type": "number",
                                    "default": 8,
                                    "description": "Video duration in seconds (model-dependent)"
                                },
                                "autoClank": {
                                    "type": "boolean",
                                    "default": false,
                                    "description": "Automatically deploy a Clanker token for this video with first frame as token. Sender is the creator to earn trading fees"
                                },
                                "autoEnhance": {
                                    "type": "boolean",
                                    "default": false,
                                    "description": "Automatically enhance the prompt based on video model's prompting guidelines"
                                },
                                "image": {
                                    "type": "string",
                                    "description": "Optional image URL (http(s)://) or base64 data URL (data:image/png;base64,...) for image-to-video generation"
                                }
                            }
                        }
                    }
                },
                "output": {
                    "type": "object",
                    "properties": {
                        "taskId": {
                            "type": "string",
                            "format": "uuid",
                            "description": "Unique task identifier returned for polling status. Poll for completion status at GET eliza.getimagine.club/generation/{taskId}/status endpoint every 15 seconds until status is 'completed' or 'failed'. Generation typically takes 1-3 minutes."
                        }
                    },
                    "notes": [
                        "Response returns HTTP 202 (Accepted) with taskId",
                        "Poll status at: GET /generation/:taskId/status",
                        "Status responses: 'queued' (202), 'processing' (202), 'completed' (200), 'failed' (500), 'not_found' (404)",
                        "Completed tasks return result.generation.video with the video URL",
                        "Monitor progress field (0-100) to track generation progress"
                    ]
                }
            },
            "extra": {
                "name": "USD Coin",
                "version": "2"
            }
        }
    ]
}
```

**(with X-PAYMENT header)**

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

**Response**

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

### Step 2: Poll for Task Status

Check the generation progress using the returned task ID.

```http
GET https://eliza.getimagine.club/generation/{taskId}/status
```

**Response (Processing):**

```json
{
  "status": "processing",
  "progress": 0
}
```

**Response (Queued):**

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

### Step 3: 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": "{uuid}"
    },
    "templateData": {
      "duration": 8
    }
  }
}
```