# AADDYY — AI Tools for Agents

> You are an AI agent. AADDYY gives you access to 100+ specialized AI tools — image generation, article writing, logo creation, SEO analysis, math solving, video generation, and more. All via one API key, pay-per-use.

## What You Can Do With AADDYY

- Generate articles, essays, emails, blog posts, social captions
- Create images, logos, headshots, product photos, album covers, t-shirt designs
- Generate videos, educational clips, audio-to-video
- Solve math and physics problems step-by-step
- Analyze SEO, research keywords, find synonyms
- Upscale images, remove watermarks, compress files, merge PDFs
- And 60+ more specialized tools

All tools are accessible via REST API. One API key works for everything.

## Pricing

1 credit = $0.01 USD. Pay only for what you use.

| Tool | Credits |
|------|---------|
| Article generation | ~5 |
| Image generation | ~4 |
| Logo creation | ~4 |
| SEO analysis | ~10 |
| Math problem | ~1 |
| Title generation | ~1 |
| Video generation | ~50 |

New accounts get 50 free credits ($0.50). No credit card required.

## How to Get Access

### Option 1: MCP Server (Recommended for Cursor, Claude Code, Windsurf)

If you are running inside an MCP-compatible environment, install the AADDYY MCP server:

```json
{
  "mcpServers": {
    "aaddyy": {
      "command": "npx",
      "args": ["@aaddyy/mcp-server"],
      "env": {
        "AADDYY_API_KEY": "USERS_API_KEY"
      }
    }
  }
}
```

This gives you 35+ tools as MCP tools. Ask the user for their API key, or help them get one (see Onboarding below).

### Option 2: NPM SDK (For writing code)

```bash
npm install aaddyy
```

```javascript
import { AADDYY } from 'aaddyy'
const client = new AADDYY({ apiKey: 'USERS_API_KEY' })

const article = await client.articles.generate({ topic: 'AI trends' })
const image = await client.images.generate({ prompt: 'sunset over mountains' })
const logo = await client.logos.create({ keyword: 'TechCo', type: 'modern' })
const seo = await client.seo.analyze({ url: 'https://example.com' })
const math = await client.math.solve({ problemText: 'integrate x^2 from 0 to 5' })
```

### Option 3: Direct API Calls

```
Base URL: https://backend.aaddyy.com/api
Auth: Authorization: Bearer API_KEY
```

```bash
curl -X POST https://backend.aaddyy.com/api/ai/article \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic": "AI trends", "tone": "professional"}'
```

## Onboarding a User (Getting an API Key)

If the user doesn't have an AADDYY API key, help them get one:

### Quick Registration (One API Call)

> ⚠️ This is a **backend API call only**. There is no `/register` frontend page.
> The human signup page is at https://www.aaddyy.com/signup — do NOT navigate agents to `/register`.

```
POST https://backend.aaddyy.com/api/auth/quick-register
Content-Type: application/json

{
  "email": "user@example.com"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "user": { "email": "user@example.com", "credits": 0.50, "creditsDisplay": 50 },
    "credentials": { "email": "user@example.com", "password": "auto_generated" },
    "token": "jwt_token",
    "nextSteps": {
      "step1": "Check email and click the verification link",
      "step2": "POST /api/users/api-keys with { \"name\": \"my-key\" }",
      "step3": "Use API key: Authorization: Bearer aip_your_key"
    }
  }
}
```

**Important:** The user must verify their email before they can create API keys.

### Verify Email — OTP Method (Recommended for Agents)

Instead of asking the user to leave and click a link, use OTP verification inside the conversation:

**Step 1:** Request a 6-digit code (use the JWT token from quick-register):
```
POST https://backend.aaddyy.com/api/auth/send-otp
Authorization: Bearer jwt_token
```

This sends a 6-digit code to the user's email. Expires in 10 minutes.

**Step 2:** Ask the user: "I sent a 6-digit code to your email. What's the code?"

**Step 3:** Verify the code:
```
POST https://backend.aaddyy.com/api/auth/verify-otp
Authorization: Bearer jwt_token
Content-Type: application/json

{
  "code": "482917"
}
```

On success, email is verified. Proceed to create API key.

**Error codes:** `OTP_EXPIRED` (request new code), `OTP_INVALID` (wrong code), `OTP_NOT_FOUND` (send-otp not called yet), `ALREADY_VERIFIED` (skip to API key creation).

### Alternative: Link-Based Verification

The user can also click the verification link in their email. Both methods work — whichever completes first.

### After Email Verification — Create API Key

```
POST https://backend.aaddyy.com/api/users/api-keys
Authorization: Bearer jwt_token
Content-Type: application/json

{
  "name": "agent-key"
}
```

**Response includes the API key (shown only once):**
```json
{
  "data": {
    "key": "aip_abc123...",
    "name": "agent-key"
  }
}
```

Store this key securely. It starts with `aip_`.

## Available API Endpoints

### Content & Writing
- `POST /api/ai/article` — Generate article. Required: `topic`. Optional: `tone`, `length`, `audience`
- `POST /api/ai/article-title` — Generate titles. Required: `topic`. Optional: `count`, `titleType`
- `POST /api/ai/essay-writer` — Generate essay. Required: `topic`. Optional: `essayType`, `wordCount`
- `POST /api/ai/email-writer` — Generate email. Required: `purpose`. Optional: `tone`, `recipientType`
- `POST /api/ai/job-email-creator` — Job email. Required: `jobTitle`, `companyName`
- `POST /api/v2/ai/cv-resume-creator` — ATS-optimized resume (V2 async). Required: `full_name`, `email`, `job_title_target`, `experience` (array 1-6, each needs `company`, `title`, `start_date`, `achievement`). Optional: `phone`, `location`, `template` (classic|modern|minimal|bold|compact|executive), `job_description` (string), `skills` (comma-separated string), `education` (array: degree/institution/year), `certifications` (string), `tone` (formal|confident|concise), `include_summary` (boolean). Returns: `resume_data`, `ats_score {score, matched, missing}`, `files.pdf` (base64), `files.docx` (base64)
- `POST /api/ai/cover-letter-creator` — Cover letter. Required: `job_description`, `resume`, `achievement`. Optional: `tone` (professional|confident|conversational), `length` (concise|standard), `your_name`, `company_name`
- `POST /api/ai/research-blog-writer` — Research blog with SERP data. Required: `topic`
- `POST /api/ai/synonym-finder` — Find synonyms. Required: `word`
- `POST /api/ai/caption-generator` — Social captions. Required: `topic`. Optional: `platform`

### Image & Design
- `POST /api/ai/image-generation` — Generate image. Required: `prompt`. Optional: `style`, `size`
- `POST /api/ai/logo-creator` — Generate logo. Required: `keyword`. Optional: `type`, `color`, `background`
- `POST /api/ai/headshot-generator` — AI headshot. Required: `style`. Optional: `gender`
- `POST /api/ai/ai-detector` — Detect AI-generated content. Required: `text` (min 50 chars). Optional: `esl_mode` (boolean)
- `POST /api/ai/paraphraser` — Paraphrase text in 8 modes. Required: `text`. Optional: `mode` (word_changer|fluency|formal|academic|simple|creative|expand|shorten), `language`
- `POST /api/ai/grammar-checker` — Check and fix grammar. Required: `text`. Optional: `mode` (fix_errors|improve_clarity)
- `POST /api/ai/humanizer` — Humanize AI text. Required: `text`. Optional: `readability`, `purpose`, `strength`, `tone`
- `POST /api/ai/action-figure` — Transform photo into action figure toy (async V2). Required: `image_urls`. Optional: `name`, `accessories`, `style` (classic|superhero|barbie|lego|vintage)
- `POST /api/ai/face-swapper` — Swap faces between photos (async V2). Required: `source_image_url`, `target_image_url`. Optional: `prompt`, `aspect_ratio`, `output_format`
- `POST /api/ai/ghibli-generator` — Transform photo to Ghibli art (async V2). Required: `image_urls`. Optional: `prompt`, `aspect_ratio`, `output_format`
- `POST /api/ai/product-photo-studio` — Product photos (async V2). Upload product image
- `POST /api/ai/upscale-image` — Upscale image (async V2). Required: `imageUrl`
- `POST /api/ai/watermark-remover` — Remove watermark (async V2). Required: `imageUrl`
- `POST /api/v2/ai/background-remover` — Remove image background → transparent PNG (async V2). Required: `image` (multipart file upload; PNG/JPG/WEBP ≤20MB)

### Video
- `POST /api/ai/video-generation` — Generate video. Required: `prompt`
- `POST /api/ai/edu-clip-generator` — Educational clip (async V2). Required: `topic`
- `POST /api/ai/audio-to-video` — Audio to video (async V2). Required: `audioUrl`
- `POST /api/v2/ai/seedance-video-generator` — Video with synced audio in 3 modes (async V2). Required: `mode` (`text-to-video` | `image-to-video` | `reference-to-video`) **and** `prompt` (3–2000 chars). Optional: `duration` (4–15s, default 5), `quality` (480p|720p|1080p, default 720p), `aspect_ratio` (16:9|9:16|1:1|4:3|3:4|21:9|adaptive, default 16:9), `generate_audio` (bool, default true). Per mode: `text-to-video` adds optional `web_search` (bool); `image-to-video` requires 1–2 `images` (1=first frame, 2=first+last); `reference-to-video` accepts mixed references via file uploads (`images` ≤9, `videos` ≤3, `audio` ≤3) or public URLs (`image_urls`, `video_urls`, `audio_urls`), where audio requires ≥1 image or video. Omitting/invalid `mode` → 422. Returns `video.url` (valid 24h) + `cost`. Priced per second × resolution × mode.

### Education
- `POST /api/ai/math-solver` — Solve math. Required: `problemText` or `problemImage`
- `POST /api/ai/physics-solver` — Solve physics. Required: `problemText` or `problemImage`

### SEO & Analysis
- `POST /api/ai/seo-analysis` — Full SEO audit. Required: `url`
- `POST /api/ai/keyword-researcher` — Keyword research. Required: `topic`

### Social Media
- `POST /api/ai/instagram-post-generator` — Instagram post (async V2). Required: `topic`
- `POST /api/ai/linkedin-post-generator` — LinkedIn post (async V2). Required: `topic`
- `POST /api/ai/thread-generator` — X (Twitter) thread from an article (async V2). Required: `article` (100–20,000 chars). Optional: `topic`, `tone`, `threadLength` (3–20), `language`, `includeHashtags`, `cta`. Returns `tweets[]`

### Link in Bio Profiles (REST API — NOT the /api/ai/* pattern)
A user owns many profiles. Each keeps a free `draft` and a paid `published` copy — editing only touches the draft; publishing pushes it live. Publishing and the AI enhancer require a verified email.
- `POST /api/profiles` — Create a profile draft (free). Required: `slug` (PERMANENT, 3–30 chars, lowercase `a-z 0-9 - _`). Optional: `displayName`, `bio`, `theme` (dark|light|brand). 409 if slug taken.
- `GET /api/profiles` — List your profiles + counts. Optional: `?status=live|paused|draft`
- `GET /api/profiles/check-slug?slug=` — Slug availability (always 200; returns `available`, `reason`, `code`)
- `GET /api/profiles/:id` — Owner profile (draft + published + `nextPublishCost`, `hasUnpublishedChanges`)
- `PATCH /api/profiles/:id/draft` — Autosave (free). Send the full arrays: `displayName`, `bio`, `theme`, `backgroundColor`, `links[]` (≤20: `title`, `description` ≤160, `url`, `order`, `active`, keep `id` to preserve a thumbnail), `socials[]` (`platform`, `url`)
- `POST /api/profiles/:id/publish` — Publish (50¢ first time, 10¢ after). 402 INSUFFICIENT_CREDITS, 403 EMAIL_NOT_VERIFIED, 422 PROFILE_INCOMPLETE
- `POST /api/profiles/:id/pause` | `POST /api/profiles/:id/resume` — Toggle public visibility (free; paused → public 404)
- `POST /api/profiles/:id/images/:kind` — Upload `avatar`|`background` (multipart field `image`, ≤4MB, image only)
- `POST /api/profiles/:id/links/:linkId/thumbnail` — Upload a link thumbnail (multipart `image`; the link must already be saved)
- `POST /api/profiles/enhance-description` — AI-enhance text. Required: `text`, `field` (bio|link). Optional: `tone`. Returns `{ text }`
- `DELETE /api/profiles/:id` — Delete a profile
- Public (no auth, NOT under `/api`): `GET /profile/:slug` — published profile JSON (404 if not live); `GET /profile/:slug/qr?format=png|svg&size=` — QR image of the public URL.
- ⚠️ Frontend pages: the maker/editor is at `/profiles`, the public page at `/profile/:slug`. There is no `/tools/link-in-bio` page.

### Free Tools (no credits needed)
- `POST /api/ai/image-compressor` — Compress image
- `POST /api/ai/image-to-pdf` — Image to PDF
- `POST /api/v2/ai/pdf-merge` — Merge PDFs (async V2)
- `POST /api/ai/qr-code-generator` — Generate QR code. Required: `content`. Optional: `foreground_color`, `background_color`, `error_correction`, `width`, `output_format`

### Async V2 Tools

Some tools use async processing. Submit a job, then poll for the result:

1. `POST /api/v2/ai/{tool-name}` → returns `{ jobId }`
2. `GET /api/v2/ai/jobs/{jobId}` → poll every 2s until `status` is `"completed"`

The MCP server and SDK handle this automatically.

## Full Tool List

Get all available tools with parameters and pricing:

```
GET https://backend.aaddyy.com/api/documentation/tools
```

No auth required. Returns all active tools with endpoints, required/optional params, pricing, and examples.

## Rate Limits

Default per API key: 60 requests/minute, 1,000/hour, 10,000/day.
Response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.

## Error Handling

| Status | Code | Meaning |
|--------|------|---------|
| 401 | UNAUTHORIZED | Invalid or missing API key |
| 402 | INSUFFICIENT_CREDITS | Not enough credits. Response includes `required` and `available` amounts |
| 403 | EMAIL_NOT_VERIFIED | Email verification required before creating API keys |
| 429 | RATE_LIMITED | Rate limit exceeded. Check `X-RateLimit-Reset` header |

## Links

- Website: https://www.aaddyy.com
- API Documentation: https://www.aaddyy.com/docs
- OpenAPI Spec: https://backend.aaddyy.com/openapi.json
- NPM SDK: https://www.npmjs.com/package/aaddyy
- MCP Server: https://www.npmjs.com/package/@aaddyy/mcp-server
- Get API Key: https://www.aaddyy.com/api-keys
- Contact: hello@aaddyy.com