# Iconly API — Vector Generation Skills

> Use this file to teach AI agents and LLMs how to generate SVG vectors with the Iconly REST API.

## Authentication

All requests require an API key in the `X-API-Key` header. Keys use the `ik_` prefix.

```
X-API-Key: ik_your_api_key_here
```

Generate a key from **Settings > API Access** in your Iconly dashboard (Pro or Max plan required).

---

## Generate Vector

```
POST https://iconly.ai/api/generate-vector/
Content-Type: application/json
X-API-Key: ik_your_api_key_here
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `subject` | string | — | **Required.** Text description of the vector (e.g. `"mountain landscape"`, max 200 characters) |
| `style` | string | `"simple"` | Vector style — see Styles below |
| `save` | boolean | `false` | Save the generated vector to the user's Iconly library |
| `name` | string | subject | Custom name for the saved library icon (only used when `save` is `true`) |

### Styles

| Style | Description |
|-------|-------------|
| `simple` | Clean, modern stroke-only icon with minimal detail and uniform stroke width |
| `detailed` | Rich illustration with varied line weights, interior details, and textures |
| `duotone` | Flat two-color illustration using filled shapes (no strokes) |
| `filled` | Solid filled shapes with a single accent color and optional thin outlines |
| `animated` | Clean stroke icon with looping CSS animations (rotate, translate, scale, opacity, draw-on effects) |

### Response

```json
{
  "success": true,
  "svg": "<svg viewBox=\"0 0 100 100\" ...>...</svg>",
  "name": "mountain landscape",
  "remaining_tokens": 482,
  "icon_id": "uuid-string"  // only present when save=true
}
```

### Token Cost

Each vector generation costs **18 tokens**.

### Example

```json
{
  "subject": "rocket ship launching",
  "style": "animated",
  "save": true,
  "name": "rocket-launch"
}
```

---

## Saving Vectors to Library

### Option 1: Save on Generation

Pass `save: true` in the generate request. The vector is saved immediately and you receive an `icon_id` in the response.

### Option 2: Save Separately

Use the library add endpoint after generation:

```
POST https://iconly.ai/api/library/add/
Content-Type: application/json
X-API-Key: ik_your_api_key_here
```

```json
{
  "name": "rocket-launch",
  "icon_type": "vector",
  "svg_data": "<svg viewBox=\"0 0 100 100\" ...>...</svg>"
}
```

Response:

```json
{
  "success": true,
  "icon_id": "uuid-string",
  "css_class": "cv-rocket-launch",
  "icon_type": "vector"
}
```

### Listing Library Vectors

```
GET https://iconly.ai/api/library/list/
X-API-Key: ik_your_api_key_here
```

Vector icons in the response have `"icon_type": "vector"` and include an `svg_data` field with the raw SVG markup.

### Downloading a Vector

```
GET https://iconly.ai/api/library/download/?id={icon_id}&format=svg
X-API-Key: ik_your_api_key_here
```

Returns the raw `.svg` file.

---

## Important Notes

- **Output format:** Vectors are always returned as raw SVG markup (not raster images). The SVG uses a `viewBox` of `0 0 100 100` and is fully scalable.
- **Animated vectors:** The `animated` style embeds CSS `@keyframes` inside a `<style>` element within the SVG. These animations loop infinitely and work in browsers and most SVG viewers.
- **No post-processing:** Unlike raster icons, vectors do not support recolor, thickness adjustment, smooth edges, or crop/recenter post-processing. If you need a different color or style, generate a new vector with an updated subject description (e.g. `"blue rocket ship"`).
- **Not for social graphics or email templates:** Vector generation is a standalone tool. Vectors are not used as inputs for social creative or email template generation — use the Icon Generation endpoint for those workflows instead, as icon generation is significantly faster.
- **Shell-based agents and Cloudflare:** If saving vectors via `POST /api/library/add/` using shell commands, avoid Python's `urllib.request` (Cloudflare blocks its User-Agent with a 403 / error code 1010). Use `curl` or Python `requests` instead. SVG payloads are small enough for standard `curl -d '...'`, but if you also work with raster `image_data` (which is 200–500 KB base64), see the **"Saving Images: Handling Large Payloads"** section in the Icon Generation skills file.

---

## Token & Account Info

```
GET https://iconly.ai/api/tokens/
X-API-Key: ik_your_api_key_here
```

Returns current token balance, monthly cap, and bonus tokens.

---

## Error Handling

| Status | Meaning |
|--------|---------|
| `400` | Missing or invalid parameters (e.g. empty subject, subject too long) |
| `403` | Account not verified, or insufficient permissions |
| `429` | Insufficient tokens or rate limited |
| `500` | Generation failed (AI did not return valid SVG) |
| `503` | Vector generation service unavailable |

All errors return `{"error": "message"}`.