API Documentation

API Documentation for GroqTales

GroqTales provides a set of APIs that allow developers to interact with the platform programmatically. These APIs enable integration with the AI story generation, NFT minting, and user management features of GroqTales. This guide is intended for developers who wish to build applications or services that leverage GroqTales' capabilities.

Note: The API documentation is a work in progress. As GroqTales evolves, more endpoints and features will be added. Check back for updates or contribute to the API development via the Contributing Guide.

Table of Contents

• Getting Started
• Authentication
• Base URL
• API Endpoints
  • Story Generation
  • NFT Minting
  • User Management
• Error Handling
• Rate Limits
• SDKs and Libraries
• Troubleshooting
• Next Steps

Getting Started

To begin using the GroqTales API, you'll need:

1. API Key: Currently, GroqTales may require an API key for certain operations (like AI story generation). Obtain your key by signing up or connecting a wallet, then check your account settings or profile for an API key section. If not yet implemented, API access may be tied to wallet authentication (see Authentication).
2. Wallet Connection: For blockchain-related operations (e.g., NFT minting), ensure you have a connected cryptocurrency wallet (MetaMask, WalletConnect, etc.) set to the Monad Testnet or Mainnet.
3. Development Environment: Set up a development environment with tools to make HTTP requests (e.g., Postman, cURL, or a programming language like Node.js with axios or fetch).

Authentication

GroqTales API authentication is primarily handled through wallet-based signatures or API keys:

• Wallet-Based Authentication: For endpoints involving blockchain operations (like NFT minting), authenticate by signing a message with your wallet. This typically happens automatically when using the GroqTales frontend, but for direct API calls, you'll need to include a signature or connect via a Web3 provider.

• API Key: For non-blockchain operations (like story generation), include your API key in the request header:

  Authorization: Bearer YOUR_API_KEY

  or as a query parameter if headers are not supported:

  ?api_key=YOUR_API_KEY

Specific authentication methods will be detailed per endpoint as the API matures.

Base URL

All API requests should be made to the base URL of the GroqTales platform. As of now, since GroqTales is under active development, the base URL for API calls is not finalized. For local development:

http://localhost:3000/api

For production (when available):

https://groqtales.com/api

Check the latest repository updates or announcements for the official production API URL once deployed.

API Endpoints

Below are the primary categories of API endpoints that GroqTales plans to support. Detailed specifications for each endpoint will be added as they are implemented.

Groq AI Service

Endpoints for interacting directly with the centralized Groq AI service.

• Check Available Models (GET /api/groq/models)

  • Description: Returns all recognized Groq models and their token budgets.
  • Query Params: ?action=test (optional) validates API credentials.
  • Response (example):

    {
      "models": { "PRIMARY": "llama-3.3-70b-versatile" },
      "default": "llama-3.3-70b-versatile",
      "tokenBudgets": { "short": 800 }
    }

• Groq Multiplex Action (POST /api/groq)

  • Description: Primary interface for story, ideas, analysis, or improvement generation.
  • Request Body (example for analysis):

    {
      "action": "analyze",
      "content": "Story text..."
    }

  • Response (example):

    {
      "result": { "sentiment": "positive", "genres": ["fantasy"] },
      "model": "llama-3.1-8b-instant",
      "tokensUsed": { "total": 120 }
    }

Story Generation

Endpoints for generating AI-powered stories using the Groq AI backend. They interact with groqService using a structured prompt engineering system with 70+ configurable parameters. See the AI Prompt Engineering wiki page for the full parameter reference.

• Generate Story (POST /api/v1/stories/generate)

  • Description: Generate a story based on provided parameters using llama-3.3-70b-versatile.

  • Request Body (example — all fields except genre are optional):

    {
      "title": "The Last Signal",
      "genre": "Science Fiction",
      "subgenre": "Cyberpunk",
      "target_format": "story_and_comic",
      "word_count_target": 2500,
      "main_characters": [
        {
          "name": "Kai",
          "age": 28,
          "role": "Protagonist",
          "traits": ["resourceful", "haunted"],
          "background": "former corporate hacker"
        }
      ],
      "central_conflict": "A hacker discovers a sentient AI trapped in a server farm",
      "atmosphere": "noir",
      "tone": "tense and suspenseful",
      "ending_type": "bittersweet",
      "violence_level": "moderate",
      "romance_level": "none",
      "language_level": "mild profanity",
      "forbidden_content": "no sexual content involving minors",
      "creativity_level": "high",
      "comic_panel_count_target": 8
    }

  • Response (structured JSON):

    {
      "title": "The Last Signal",
      "genre": "Science Fiction",
      "wordCountApprox": 2480,
      "summary": "A former hacker discovers a sentient AI...",
      "chapters": [
        {
          "chapterNumber": 1,
          "chapterTitle": "Ghost in the Grid",
          "chapterSummary": "Kai breaks into NovaCorp...",
          "text": "The rain fell sideways through the neon haze..."
        }
      ],
      "characters": [
        {
          "name": "Kai",
          "role": "Protagonist",
          "shortDescription": "A haunted ex-hacker seeking redemption",
          "arcSummary": "Moves from self-preservation to self-sacrifice"
        }
      ],
      "themes": {
        "primary": ["consciousness", "freedom"],
        "secondary": ["corporate exploitation"]
      },
      "contentWarnings": ["moderate violence"],
      "styleNotes": {
        "tone": "tense and suspenseful",
        "voice": "close third person",
        "pacing": "fast-paced"
      },
      "comicScript": {
        "enabled": true,
        "panels": [
          {
            "panelNumber": 1,
            "pageNumber": 1,
            "location": "Server wing — abandoned floor",
            "time": "Night",
            "visualDescription": "Wide shot: Kai crouches at a window...",
            "charactersPresent": ["Kai"],
            "dialogue": [],
            "caption": "Some doors are easier to break into than out of.",
            "emotionalBeat": "Isolation, tension"
          }
        ]
      },
      "nftMetadata": {
        "shortBlurb": "A former hacker finds something alive in the servers...",
        "tags": ["cyberpunk", "AI", "noir"],
        "recommendedMintEditionSize": 50
      }
    }

  • Headers: Authorization: Bearer YOUR_API_KEY

  • Status: Active

NFT Minting

Endpoints for minting stories as NFTs on the Monad blockchain.

• Mint NFT (POST /nfts/mint)

  • Description: Mint a generated story as an NFT. Requires a connected wallet and Monad network.

  • Request Body (example):

    {
      "storyId": "story-12345",
      "metadata": {
        "title": "The Lost Kingdom",
        "description": "A knight's epic journey...",
        "content": "Full story content here...",
        "authorAddress": "0xYourWalletAddress",
        "coverImage": "https://example.com/image.jpg",
        "genre": "fantasy, adventure"
      }
    }

  • Response (example):

    {
      "tokenId": "nft-67890",
      "transactionHash": "0xTransactionHash",
      "nftUrl": "/nft-gallery/67890",
      "status": "minted",
      "blockchain": "Monad Testnet"
    }

  • Headers: Requires wallet signature or Web3 authentication.

  • Status: Planned/In Development (see /api/monad/mint in current codebase for early implementation).

User Management

Endpoints for managing user accounts and profiles.

• Get User Profile (GET /users/profile)

  • Description: Retrieve the profile information associated with the connected wallet or API key.

  • Response (example):

    {
      "address": "0xYourWalletAddress",
      "username": "Storyteller123",
      "stories": ["story-12345"],
      "nfts": ["nft-67890"],
      "createdAt": "2023-09-01T10:00:00Z"
    }

  • Headers: Authorization: Bearer YOUR_API_KEY or wallet signature.

  • Status: Planned

Error Handling

GroqTales API responses will include standard HTTP status codes to indicate the success or failure of requests:

• 200 OK: Request successful.
• 400 Bad Request: Invalid input or missing parameters. Check the response body for specific error messages.
• 401 Unauthorized: Authentication failed. Verify your API key or wallet signature.
• 403 Forbidden: You do not have permission to access this resource.
• 429 Too Many Requests: Rate limit exceeded. See Rate Limits.
• 500 Internal Server Error: Server-side issue. Retry later or contact support.

Error responses will typically include a JSON object with details:

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Missing required field: genre"
  }
}

Rate Limits

To ensure fair usage and protect server resources, GroqTales API may impose rate limits, especially for AI story generation endpoints which are computationally intensive:

• Limit: Currently not specified as the API is in development. Expect limits like 10 requests per minute for story generation when live.
• Headers: Responses may include headers like X-Rate-Limit-Limit, X-Rate-Limit-Remaining, and X-Rate-Limit-Reset to inform you of your current rate limit status.
• Exceeding Limits: If you exceed the rate limit, you'll receive a 429 Too Many Requests error. Wait until the reset time or use a custom API key if available for higher limits.

SDKs and Libraries

While official SDKs for GroqTales are not yet available, you can interact with the API using standard HTTP clients in your preferred programming language:

• JavaScript/Node.js: Use axios or fetch for making requests. Example with axios:

  const axios = require('axios');
  
  async function generateStory(apiKey, storyData) {
    try {
      const response = await axios.post('http://localhost:3000/api/stories/generate', storyData, {
        headers: { Authorization: `Bearer ${apiKey}` },
      });
      console.log('Generated Story:', response.data);
      return response.data;
    } catch (error) {
      console.error('Error:', error.response?.data || error.message);
      throw error;
    }
  }

• Python: Use requests library for API calls.

• Web3 Integration: For blockchain operations, use libraries like ethers.js or web3.js to handle wallet signatures and interactions with Monad smart contracts.

Future updates may include official SDKs to simplify integration.

Troubleshooting

• Authentication Errors: Ensure your API key is correct and not expired. For wallet-based auth, verify your wallet is connected and on the correct network (Monad Testnet).
• Invalid Input Errors: Check the API documentation for required fields and formats. Ensure JSON payloads are properly structured.
• Network Issues: If requests timeout or fail, verify your internet connection and the API base URL. For local development, ensure your server is running (npm run dev).
• Rate Limit Exceeded: Wait for the reset period or consider using a custom API key for higher limits if supported.

For additional support, post questions in GitHub Discussions or refer to the FAQ.

Next Steps

• Explore smart contract details for blockchain integration in Smart Contracts.
• Set up a development environment with Development Setup.
• Return to the Home page for more resources.

As the GroqTales API continues to develop, this documentation will be updated with more detailed endpoints and examples. Stay tuned for enhancements to programmatically interact with our AI-powered storytelling platform!