API Documentation
Integrate Icovela's icon generation into your apps.
Quick Start
- 1
Get your API key
Go to API Keys to create one.
- 2
Make a request
Send a POST to
/api/v1/generate - 3
Get your icon
Receive a base64 PNG in the response.
curl
curl -X POST https://icovela.com/api/v1/generate \
-H "Authorization: Bearer ik_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"subject": "rocket", "style": "isometric", "color": "#2563EB"}'Authentication
All API requests (except GET /api/v1/styles) require an API key in the Authorization header:
Authorization: Bearer ik_live_YOUR_KEYAPI keys are tied to your account. Each icon generation costs 10 credits from your account balance — the same credits used on the web app.
Endpoints
GET /api/v1/styles
List available icon styles. No authentication required.
Response
{
"styles": [
{
"id": "isometric",
"name": "Isometric 3D",
"description": "Realistic miniature 3D objects",
"supportsThemeColor": false,
"supportsReferenceImages": false
}
// ...
]
}GET /api/v1/account
Check your credit balance and API usage stats.
Response
{
"credits": 500,
"apiUsage": {
"totalCalls": 42,
"totalCreditsUsed": 420,
"last30Days": { "calls": 15, "creditsUsed": 150 }
}
}POST /api/v1/generate
Generate a single icon. Costs 10 credits.
| Parameter | Type | Required | Description |
|---|---|---|---|
| subject | string | Yes | What to generate, e.g. "rocket" |
| style | string | Yes | Style ID (see /styles) |
| color | string | No | Hex color, e.g. "#2563EB" |
| quality | "low" | "medium" | No | Default: "low" |
| bgMode | "transparent" | "white" | No | Default: "transparent" |
Request
{
"subject": "rocket",
"style": "isometric",
"color": "#2563EB"
}Response
{
"image": "data:image/png;base64,iVBOR...",
"creditsUsed": 10,
"creditsRemaining": 490
}POST /api/v1/generate-set
Generate multiple icons in one request. Costs 10 credits per icon. Max 10 icons.
| Parameter | Type | Required | Description |
|---|---|---|---|
| style | string | Yes | Style ID (see /styles) |
| icons | array | Yes | Array of {subject, color?} |
| quality | "low" | "medium" | No | Default: "low" |
| bgMode | "transparent" | "white" | No | Default: "transparent" |
Request
{
"style": "candy3d",
"icons": [
{ "subject": "rocket", "color": "#EC4899" },
{ "subject": "star", "color": "#F59E0B" },
{ "subject": "heart", "color": "#EF4444" }
]
}Response
{
"icons": [
{ "subject": "rocket", "image": "data:image/png;base64,..." },
{ "subject": "star", "image": "data:image/png;base64,..." },
{ "subject": "heart", "image": "data:image/png;base64,..." }
],
"creditsUsed": 30,
"creditsRemaining": 470
}Styles Reference
| ID | Name | Theme Color |
|---|---|---|
| isometric | Isometric 3D | 3D shading only |
| minimalist3d | Minimalist 3D | Yes |
| candy3d | Candy 3D | Yes |
| glassmorphism | Glassmorphism | Yes |
| editorial | Bold Editorial | Yes |
Error Codes
All errors return a consistent format:
{ "error": { "code": "error_code", "message": "Human-readable message" } }| HTTP | Code | Description |
|---|---|---|
| 400 | invalid_input | Missing or invalid parameters |
| 400 | invalid_json | Request body is not valid JSON |
| 401 | unauthorized | Missing, invalid, or revoked API key |
| 402 | insufficient_credits | Not enough credits in your account |
| 429 | rate_limit_exceeded | Too many requests (60/min per key) |
| 500 | generation_failed | AI model failed to generate the icon |
| 500 | internal_error | Unexpected server error |
Rate Limits
Each API key is limited to 60 requests per minute (sliding window). Rate limit info is returned in response headers:
X-RateLimit-Remaining— requests remaining in current windowX-RateLimit-Reset— Unix timestamp when the window resets
Code Examples
curl
bash
curl -X POST https://icovela.com/api/v1/generate \
-H "Authorization: Bearer ik_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"subject": "rocket", "style": "isometric", "color": "#2563EB"}' \
| jq -r '.image' | sed 's/data:image\/png;base64,//' | base64 -d > icon.pngPython
python
import requests, base64
resp = requests.post(
"https://icovela.com/api/v1/generate",
headers={"Authorization": "Bearer ik_live_YOUR_KEY"},
json={"subject": "rocket", "style": "isometric", "color": "#2563EB"},
)
data = resp.json()
# Save the PNG
b64 = data["image"].split(",")[1]
with open("icon.png", "wb") as f:
f.write(base64.b64decode(b64))
print(f"Credits remaining: {data['creditsRemaining']}")Node.js
javascript
const resp = await fetch("https://icovela.com/api/v1/generate", {
method: "POST",
headers: {
"Authorization": "Bearer ik_live_YOUR_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
subject: "rocket",
style: "isometric",
color: "#2563EB",
}),
});
const { image, creditsRemaining } = await resp.json();
// Save the PNG
const b64 = image.split(",")[1];
const fs = await import("fs");
fs.writeFileSync("icon.png", Buffer.from(b64, "base64"));
console.log(`Credits remaining: ${creditsRemaining}`);Ready to start?
Create your API key