MarketOS API

Generate marketing content programmatically. BYOK — bring your own Gemini key, we handle the orchestration.

Quick Start

1. Get a Gemini API Key

Visit Google AI Studio, sign in, and create an API key. Free tier available with generous limits.

2. Make Your First Request

No account needed — use stateless BYOK mode:

curl -X POST https://marketos.org/api/v1/generate/caption \
  -H "Content-Type: application/json" \
  -H "X-Api-Keys: $(echo '{"gemini":"YOUR_GEMINI_KEY"}' | base64)" \
  -d '{
    "prompt": "New product launch for our coffee brand",
    "platform": "instagram"
  }'

3. Or Register for a Token

If you have a MarketOS license, register your keys once:

curl -X POST https://marketos.org/api/api-keys/register \
  -H "Content-Type: application/json" \
  -d '{
    "licenseKey": "MOS_XXXX-XXXX-XXXX-XXXX",
    "apiKeys": { "gemini": "YOUR_GEMINI_KEY" }
  }'

Then use the returned mos_xxx token in all requests:

Authorization: Bearer mos_xxxxxxxxxxxx

Authentication

Four authentication methods are supported, checked in this order:

Endpoints

Returns: { image?, caption, hashtags, platform, imagePrompt, enhancedBrief, imageError? }

Returns: { caption, hashtags, platform }

Returns: { title, content, topic, contentType, wordCount }

Returns: { images: [{ base64, mimeType }], model, prompt }

Image Models

Returns: { url, title, tagline, description, content }

Returns the full API schema including all 40+ content types, image models, word count options, platform list, rate limits, pricing, and agent skill references. Ideal for AI agent discovery.

Example: Full Agent Workflow

An AI agent can chain these endpoints to generate branded content:

// Step 1: Extract brand context
POST /api/v1/scrape
{ "url": "https://coffeeshop.com" }
→ { "content": "Premium artisan coffee roaster...", "title": "...", ... }

// Step 2: Generate complete marketing post
POST /api/v1/generate/marketing
{
  "prompt": "Instagram post for our new espresso blend",
  "brandContext": "Premium artisan coffee roaster...",
  "platform": "instagram"
}
→ {
  "image": { "base64": "...", "mimeType": "image/png" },
  "caption": "Every cup tells a story ☕...",
  "hashtags": ["coffee", "espresso", ...],
  "platform": "instagram",
  "imagePrompt": "...",
  "enhancedBrief": "..."
}

// Or generate individual pieces:
POST /api/v1/generate/caption
{ "prompt": "New espresso blend launch", "platform": "twitter" }

POST /api/v1/generate/content
{ "topic": "Why single-origin matters", "contentType": "blog-standard", "wordCount": "long" }

POST /api/v1/generate/image
{ "prompt": "Steaming espresso cup, morning light", "model": "imagen-4.0-generate-001" }

Pricing

Per-Request Fees (x402)

Rate Limits

30 requests per minute per token or IP. Responses include Retry-After header when limited. Plan holders have a separate 1,000 requests/day quota that resets at midnight UTC.

Errors

x402 Protocol Support

MarketOS supports the x402 payment protocol for autonomous AI agent payments. No signup, no API keys, no merchant account needed.

How It Works

1. Agent sends request without auth
   → Server responds 402 with X-PAYMENT-REQUIRED header

2. Agent reads payment requirements from header:
   - Amount (e.g., 0.05 USDC)
   - Wallet address
   - Network (Base mainnet)

3. Agent signs USDC payment on Base blockchain

4. Agent retries request with:
   - X-PAYMENT header (signed payment payload)
   - X-Api-Keys header (base64 Gemini key for BYOK)

5. Server verifies payment via Coinbase facilitator
   → Returns the generated content

Payments are in USDC on Base (Ethereum L2). The Coinbase facilitator verifies payments at no cost to either party. Agents using x402-compatible wallets can pay autonomously without human intervention.

AI Provider

All API endpoints use Google Gemini exclusively:

The scrape endpoint also uses Jina Reader API for web content extraction. A Jina API key is optional but recommended for higher rate limits.

Agent Discovery

MarketOS provides multiple discovery mechanisms for AI agents: