How to Connect AI Agents to MarketOS

The MarketOS Agentic API lets AI agents generate marketing content programmatically — images, captions, hashtags, blog posts, and 100+ content types. This tutorial walks through the setup from scratch.

Prerequisites

• A Google Gemini API key (free tier: aistudio.google.com/apikey)
• A MarketOS plan (subscription or lifetime) for included API access, OR a crypto wallet for x402 per-request payment
• curl, Python, Node.js, or any HTTP client

Step 1: Get Your Gemini API Key

MarketOS is BYOK (Bring Your Own Key). You need at minimum a Google Gemini API key. The free tier gives you generous rate limits for testing.

1. 1

   Go to Google AI Studio and sign in with your Google account.

2. 2

   Click "Create API Key" and copy the key. It starts with AIza.

3. 3

   Store it securely. You'll pass this to MarketOS with every request.

Step 2: Choose Your Auth Method

MarketOS supports multiple authentication modes. Pick the one that fits your use case:

Step 3: Make Your First API Call

Let's start with the simplest approach — stateless BYOK. Encode your API keys as base64 JSON and pass them in the header:

Generate a Caption (curl)

# Encode your keys as base64
KEYS=$(echo -n '{"gemini":"YOUR_GEMINI_KEY"}' | base64)

curl -X POST https://marketos.org/api/v1/generate/caption \
  -H "Content-Type: application/json" \
  -H "X-Api-Keys: $KEYS" \
  -d '{
    "prompt": "New product launch for our eco-friendly water bottle",
    "platform": "instagram",
    "hashtagThemes": ["sustainability", "eco-friendly", "hydration"]
  }'

Response:

{
  "caption": "🌊 Meet your new daily companion. Our eco-friendly water bottle is crafted from 100% recycled materials — because staying hydrated shouldn't cost the planet. 🌿 Make the switch today. 💧",
  "hashtags": ["sustainability", "ecofriendly", "hydration", "reusablebottle", "zerowaste", "greenproducts", "sustainableliving", "waterbottle", "ecoproducts", "plasticfree"],
  "platform": "instagram"
}

Generate a Full Social Post (curl)

The /v1/generate/marketing endpoint does everything in one call — parses your brief, generates an image, and creates a caption with hashtags:

curl -X POST https://marketos.org/api/v1/generate/marketing \
  -H "Content-Type: application/json" \
  -H "X-Api-Keys: $KEYS" \
  -d '{
    "prompt": "Instagram post promoting our summer sale, 30% off everything",
    "platform": "instagram",
    "style": "modern-minimal",
    "imageModel": "imagen-4.0-generate-001",
    "aspectRatio": "1:1"
  }'

The response includes image.base64 (the generated image), caption, hashtags, and the imagePrompt that was used.

Generate a Blog Post (Python)

import requests
import base64
import json

keys = base64.b64encode(
    json.dumps({"gemini": "YOUR_GEMINI_KEY"}).encode()
).decode()

response = requests.post(
    "https://marketos.org/api/v1/generate/content",
    headers={
        "Content-Type": "application/json",
        "X-Api-Keys": keys,
    },
    json={
        "topic": "Benefits of AI-powered marketing automation",
        "contentType": "blog-standard",
        "wordCount": "long",
        "brandContext": "B2B SaaS company targeting marketing teams"
    }
)

result = response.json()
print(result["title"])
print(result["content"][:500])

Step 4: Add Brand Context

For on-brand content, first scrape your website to extract brand context, then pass it to generation endpoints:

# Step 1: Extract brand context
curl -X POST https://marketos.org/api/v1/scrape \
  -H "Content-Type: application/json" \
  -H "X-Api-Keys: $KEYS" \
  -d '{"url": "https://yourcompany.com"}'

# Step 2: Use the returned brandContext in generation
curl -X POST https://marketos.org/api/v1/generate/marketing \
  -H "Content-Type: application/json" \
  -H "X-Api-Keys: $KEYS" \
  -d '{
    "prompt": "LinkedIn post about our Q1 results",
    "platform": "linkedin",
    "brandContext": "PASTE_BRAND_CONTEXT_HERE"
  }'

Step 5: Discover Capabilities Programmatically

Agents can discover all available endpoints, content types, and image models via the info endpoint (no auth required):

curl https://marketos.org/api/v1/info | jq '.endpoints'

Or read the llms.txt file for a Markdown overview optimized for LLM consumption. See our guide on what llms.txt is for more context.

Error Handling

The API returns standard HTTP status codes with JSON error bodies:

For the full API reference, visit the API documentation.