---
name: creative-agent
description: Install, configure, and use creative-agent from an external AI agent without opening the browser.
---

# creative-agent

Use this skill when an external AI agent needs to create, host, serve, or
iterate a creative without using the web UI.

## What This Service Provides

- Canonical skill URL: `/skill.md`
- Skill discovery URL: `/skills`
- HTTP MCP endpoint: `/mcp`
- REST asset API: `/api/assets`
- Browser-free creative creation, hosting, serving, downloading, iteration, and history lookup
- Creative-agent hosted URLs so downstream agents can reference creatives without copying large image payloads
- Authentication with the same `SITE_PASSWORD` used by the app

## Serving and Downloading Creatives

When creative-agent creates an asset, the response includes hosted URLs:

- `served_url` - preferred URL for displaying or embedding the creative
- `download_url` - preferred URL for downloading the creative
- `url` - backwards-compatible alias for `served_url`
- `direct_url` - underlying storage URL; use only as a fallback

In most workflows, pass `served_url` or `download_url` to downstream systems
instead of copying the image bytes into prompts, messages, or intermediate
storage. This keeps payloads small and lets creative-agent remain the host of
record for generated creatives.

## Required Server Environment

The deployed service must have these environment variables:

- `AI_GATEWAY_API_KEY` - Vercel AI Gateway key for image generation
- `BLOB_READ_WRITE_TOKEN` - Vercel Blob token for image and conversation storage
- `SITE_PASSWORD` - shared bearer token for headless clients
- `APP_URL` - public app URL, recommended so returned creative URLs point at the deployment
- `BLOB_PUBLIC_URL` - blob store public base URL, required for `/assets/:image_id` proxy URLs

For local development or automated validation without Vercel Blob, set
`LOCAL_ASSET_STORAGE_DIR` to a writable directory. The service will store
images and conversation JSON locally and return `/local-assets/:image_id.png`
URLs. Do not use local storage for production deployments that need durable
assets.

## Agent Setup With MCP

Use MCP when your agent can call tools.

### Streamable HTTP MCP

```json
{
  "mcpServers": {
    "creative-agent": {
      "url": "https://YOUR_DOMAIN/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SITE_PASSWORD"
      }
    }
  }
}
```

### Stdio-Only MCP Clients

Use `mcp-remote` as a bridge:

```json
{
  "mcpServers": {
    "creative-agent": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR_DOMAIN/mcp",
        "--header",
        "Authorization: Bearer YOUR_SITE_PASSWORD"
      ]
    }
  }
}
```

## Agent Setup With REST

Use REST when your agent cannot connect to MCP.

Create and host a new creative:

```bash
curl -X POST "https://YOUR_DOMAIN/api/assets" \
  -H "Authorization: Bearer YOUR_SITE_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a clean hero image for a B2B AI product",
    "format": "horizontal",
    "brand_id": "default",
    "include_text": "Innovation Starts Here"
  }'
```

Get creative history:

```bash
curl "https://YOUR_DOMAIN/api/assets/ASSET_ID" \
  -H "Authorization: Bearer YOUR_SITE_PASSWORD"
```

Create and host the next iteration:

```bash
curl -X POST "https://YOUR_DOMAIN/api/assets/ASSET_ID" \
  -H "Authorization: Bearer YOUR_SITE_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "feedback": "Make the composition brighter and add more depth"
  }'
```

## Available Asset Inputs

- `prompt` - required image brief
- `format` - `horizontal`, `vertical`, or `square`; defaults to `horizontal`
- `brand_id` - brand guidelines ID; use `default` when unsure
- `include_text` - text to render inside the generated image
- `style_override` - optional style such as `photorealistic`, `minimalist`, or `geometric`
- `negative_prompt` - things to avoid

## Expected Create Response

The create response includes:

- `asset_id` / `conversation_id` - use this for iteration and lookup
- `served_url` - creative-agent hosted URL for serving or embedding
- `download_url` - creative-agent hosted URL for downloading
- `url` - backwards-compatible alias for `served_url`
- `direct_url` - underlying storage URL, useful as a fallback
- `image_id` - generated image identifier
- `iteration` - starts at `1`
- `dimensions`, `width`, and `height`

## Operational Notes

- Keep `SITE_PASSWORD` secret. Do not put it in prompts, documents, or code.
- Prefer MCP for multi-step agent workflows; prefer REST for simple automation.
- Prefer hosted URLs over copying image bytes between agents.
- If `/assets/:image_id` URLs do not resolve, use `direct_url` and verify
  `BLOB_PUBLIC_URL` is configured on the service.
- If requests return `503`, the deployment is missing required environment variables.
- If local testing cannot write to Vercel Blob, set `LOCAL_ASSET_STORAGE_DIR`
  and restart the service.