> For the complete documentation index, see [llms.txt](https://docs.aiis.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aiis.dev/developers/api/generate.md).

# Generate

## Generate Endpoints

These endpoints accept inputs and return generated content based on the chosen model. The server handles the heavy lifting (e.g., calling GPT, DALL·E, or other LLM/image models) and returns a simple JSON response.

### Generation Endpoint

This endpoint combines text and image generation into a single streamlined request. Instead of using separate endpoints for text and image generation, the items are generated concurrently and automatically create a generation record. The endpoint calls the appropriate AI models and returns a JSON response containing the generated content along with the record ID.

**Endpoint URL:**\
`https://api.aiis.dev/v2/generations/generate`

**Request Payload:**\
The endpoint expects a JSON payload with the following fields:

* **name** (string): The token name.
* **prompt** (string): The prompt for image generation.
* **symbol** (string): The token symbol.
* **supply** (string): The token supply.
* **namePrompt** (string): Prompt for generating a token name.
* **symbolPrompt** (string): Prompt for generating a token symbol.
* **supplyPrompt** (string): Prompt for generating a token supply description.
* **temperature** (number): Required for most text generation models.
* **textModel** (string): Specifies which text generation model to use. Options include:
  * GPT-3.5 (use "GPT-3.5")
  * GPT-4 (use "GPT-4")
  * Claude
  * Gemini
  * Llama
  * Bittensor
  * AstroPepeX
* **model** (string): Specifies the image generation model to use. Options include:
  * DALLE-2 (use "DALLE-2")
  * DALLE-3 (use "DALLE-3")
  * Bittensor
  * Flux
  * CUSTOM
* **with\_ai** (boolean):
  * **true:** The endpoint applies additional AI-based enhancements to generate creative and refined outputs.
  * **false:** The endpoint bypasses AI generation and returns the provided prompt values as the output. This allows clients to use their own values without triggering extra processing.

**How It Works:**

1. **Input Validation:** The endpoint validates and casts the incoming request using a DTO.
2. **API Keys & Context:** It extracts the necessary API keys and configuration from the request context.
3. **Model-Specific Generation:**
   * **Image Generation:**\
     The endpoint selects the appropriate function (e.g., `genDalle2Image`, `genDalle3Image`, etc.) based on the `model` parameter. This function produces an image URL and returns the final prompt used for generation.
   * **Text Generation:**\
     Based on the `textModel` parameter (and ensuring that `temperature` is provided when required), the corresponding function (e.g., `generateGPT3Text`, `generateGPT4Text`, etc.) is invoked to generate text outputs such as the token name, supply, and symbol.
4. **with\_ai Parameter Behavior:**
   * If **with\_ai** is set to **true**, the endpoint calls the AI generation functions to produce enhanced, creative outputs.
   * If **with\_ai** is set to **false**, the endpoint will bypass the AI generation step and simply return the input values provided in the payload. This allows for a deterministic or fallback behavior on the client side.
5. **Record Creation:** The endpoint automatically creates a new generation record on [aiis.dev](https://aiis.dev) using the generated data.

   * **Response:** A JSON response is returned that includes the generation record ID, the generated image details, and text outputs.

   **Example Request:**

   ```bash
   curl -X POST https://api.aiis.dev/v2/generations/generate \
   -H "Content-Type: application/json" \
   -d '{
     "name": "MyToken",
     "prompt": "A futuristic cityscape at sunset",
     "symbol": "MTK",
     "supply": "1000000",
     "namePrompt": "Generate a catchy token name",
     "symbolPrompt": "Generate a short token symbol",
     "supplyPrompt": "Generate a token supply description",
     "temperature": 0.75,
     "textModel": "GPT-4",
     "model": "DALLE-2",
     "with_ai": true
   }'
   ```

   **Example Response:**

   ```json
   {
     "genId": "cm7pf0dsa0003n20fyimyos92",
     "image": {
       "url": "https://aiisdev.mypinata.cloud/ipfs/QmTJuM3wbMRPeFqWnckJwXqbe5Lty6LHgCWuta6fJG1b55",
       "prompt": "A futuristic cityscape at sunset"
     },
     "text": {
       "name": "DankShibeCoin",
       "supply": "1000000",
       "symbol": "DSC"
     }
   }
   ```

   \
   **List Generations:**

   `https://api.aiis.dev/v2/generations/list`\
   Returns a paginated list of shared generation records. Query parameters include:

   * **page:** The page number.
   * **pageSize:** The number of records per page.
   * **sortBy:** Sorting criteria (e.g., "latest", "mostUpvoted", "deployed", "mcap", or "bumps").
   * **tokensOnly:** (Optional) If true, only generations with an associated token are returned.
   * **chain:** (Optional) Filter by blockchain network.

   **Example Request:**

   ```bash
   curl -X GET "https://api.aiis.dev/v2/generations/list?page=1&pageSize=10&sortBy=latest"
   ```

   **Example Response:**

   ```json
   {
     "generations": [
       {
         "id": "cm7mjki5o001gn20faca9on1p",
         "name": "PepeChain",
         "symbol": "PEPE",
         "supply": "1000000000",
         "image_url": "https://aiisdev.mypinata.cloud/ipfs/QmSpFXJHp72Tz87oyrkZm9xjVMSBMDdSj42GpDTpTWVB47",
         "thumbnail_image_url": "https://aiisdev.mypinata.cloud/ipfs/QmYjjSdkBkLADLYCG6Hirs4StkrPY9FwGGkntZkFKB8ym3",
         "name_prompt": "make a token based on pepe...",
         "symbol_prompt": "make it funny...",
         "supply_prompt": "pi...",
         "image_prompt": "A radiant Pepe the Frog character is whimsically morphed into an enchanting chain link...",
         "temperature": 0.75,
         "llm_model": "Claude",
         "image_model": "Flux",
         "with_ai": true,
         "createdAt": "2025-02-26T23:23:31.692Z",
         "upvotes": 0,
         "token": null
       }
     ],
     "totalPages": 1313,
     "currentPage": 1
   }
   ```

**Get Generation by ID:** Fetches detailed information for a single generation record by its unique ID.

**Example Request:**

```bash
curl -X GET https://api.aiis.dev/v2/generations/cm7mfh3cs000zn20frerj7ahe
```

**Example Response:**

```json
{
  "id": "cm7mfh3cs000zn20frerj7ahe",
  "name": "StonksBrahMemeFi",
  "symbol": "STONK",
  "supply": "1000000000",
  "image_url": "https://aiisdev.mypinata.cloud/ipfs/QmZRW9zbDnoQawwr8UxFDuduG43N7p4iQn3jpHKNBBZ5yf",
  "thumbnail_image_url": "https://aiisdev.mypinata.cloud/ipfs/QmRn76B8vJvfmsQAQLHvmcbn23wRAvcCuPRASFjF32Bkyq",
  "name_prompt": "@WallStreetMav @deploybrah",
  "symbol_prompt": "@WallStreetMav @deploybrah",
  "supply_prompt": "1000000000",
  "image_prompt": "@WallStreetMav @deploybrah",
  "temperature": 0.85,
  "llm_model": "GPT-4",
  "image_model": "Flux",
  "with_ai": true,
  "createdAt": "2025-02-26T21:28:54.077Z",
  "upvotes": 0,
  "token": null
}
```

────────────────────────────\
**Note:** The separate text and image generation endpoints have been merged into the single Generation Endpoint, which both generates content and creates a corresponding record. This simplifies integration and ensures consistency across generation requests.

1. **Response:** A JSON response is returned that includes the generation record ID, the generated image details, and text outputs.

**Example Request:**

```bash
curl -X POST https://api.aiis.dev/v2/generations/generate \
-H "Content-Type: application/json" \
-d '{
  "name": "MyToken",
  "prompt": "A futuristic cityscape at sunset",
  "symbol": "MTK",
  "supply": "1000000",
  "namePrompt": "Generate a catchy token name",
  "symbolPrompt": "Generate a short token symbol",
  "supplyPrompt": "Generate a token supply description",
  "temperature": 0.75,
  "textModel": "GPT-4",
  "model": "DALLE-2",
  "with_ai": true
}'
```

**Example Response:**

```json
{
  "genId": "cm7pf0dsa0003n20fyimyos92",
  "image": {
    "url": "https://aiisdev.mypinata.cloud/ipfs/QmTJuM3wbMRPeFqWnckJwXqbe5Lty6LHgCWuta6fJG1b55",
    "prompt": "A futuristic cityscape at sunset"
  },
  "text": {
    "name": "DankShibeCoin",
    "supply": "1000000",
    "symbol": "DSC"
  }
}
```

\
**List Generations:**

`https://api.aiis.dev/v2/generations/list`\
Returns a paginated list of shared generation records. Query parameters include:

* **page:** The page number.
* **pageSize:** The number of records per page.
* **sortBy:** Sorting criteria (e.g., "latest", "mostUpvoted", "deployed", "mcap", or "bumps").
* **tokensOnly:** (Optional) If true, only generations with an associated token are returned.
* **chain:** (Optional) Filter by blockchain network.

**Example Request:**

```bash
curl -X GET "https://api.aiis.dev/v2/generations/list?page=1&pageSize=10&sortBy=latest"
```

**Example Response:**

```json
{
  "generations": [
    {
      "id": "cm7mjki5o001gn20faca9on1p",
      "name": "PepeChain",
      "symbol": "PEPE",
      "supply": "1000000000",
      "image_url": "https://aiisdev.mypinata.cloud/ipfs/QmSpFXJHp72Tz87oyrkZm9xjVMSBMDdSj42GpDTpTWVB47",
      "thumbnail_image_url": "https://aiisdev.mypinata.cloud/ipfs/QmYjjSdkBkLADLYCG6Hirs4StkrPY9FwGGkntZkFKB8ym3",
      "name_prompt": "make a token based on pepe...",
      "symbol_prompt": "make it funny...",
      "supply_prompt": "pi...",
      "image_prompt": "A radiant Pepe the Frog character is whimsically morphed into an enchanting chain link...",
      "temperature": 0.75,
      "llm_model": "Claude",
      "image_model": "Flux",
      "with_ai": true,
      "createdAt": "2025-02-26T23:23:31.692Z",
      "upvotes": 0,
      "token": null
    }
  ],
  "totalPages": 1313,
  "currentPage": 1
}
```

**Get Generation by ID:**\
`GET https://api.aiis.dev/v2/generations/:id`\
Fetches detailed information for a single generation record by its unique ID.

**Example Request:**

```bash
https://api.aiis.dev/v2/generations/cm7mfh3cs000zn20frerj7ahe
```

**Example Response:**

```json
{
  "id": "cm7mfh3cs000zn20frerj7ahe",
  "name": "StonksBrahMemeFi",
  "symbol": "STONK",
  "supply": "1000000000",
  "image_url": "https://aiisdev.mypinata.cloud/ipfs/QmZRW9zbDnoQawwr8UxFDuduG43N7p4iQn3jpHKNBBZ5yf",
  "thumbnail_image_url": "https://aiisdev.mypinata.cloud/ipfs/QmRn76B8vJvfmsQAQLHvmcbn23wRAvcCuPRASFjF32Bkyq",
  "name_prompt": "@WallStreetMav @deploybrah",
  "symbol_prompt": "@WallStreetMav @deploybrah",
  "supply_prompt": "1000000000",
  "image_prompt": "@WallStreetMav @deploybrah",
  "temperature": 0.85,
  "llm_model": "GPT-4",
  "image_model": "Flux",
  "with_ai": true,
  "createdAt": "2025-02-26T21:28:54.077Z",
  "upvotes": 0,
  "token": null
}
```

────────────────────────────\
**Note:** The separate text and image generation endpoints have been merged into the single Generation Endpoint, which both generates content and creates a corresponding record. This simplifies integration and ensures consistency across generation requests.