API Reference
REST API with JSON requests and responses.
Authentication
Include your API key in the x-api-key header.
Header
x-api-key: ic_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxBase URL
https://api.iconcraft.app/api/publicPrompts
For best results, structure prompts as modern app icon featuring [description].
Short or vague prompts are automatically enhanced for optimal icon generation.
Endpoints
generateGenerate an icon from a text prompt.
Cost: $0.25 per request
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | Must be "generate" |
| prompt | string | Yes | Visual description of the icon (max 2000 chars) |
| style | string | No | "default" | "minimal" | "clean-3d" | "frosted-glass" |
Response
{
"imageUrl": "https://icon-url...",
"requestId": "abc123",
"promptWasEnhanced": true,
"finalPrompt": "modern app icon featuring..."
}| imageUrl | URL of the generated icon (PNG, 1024x1024) |
| requestId | Unique identifier for the request |
| promptWasEnhanced | Whether the prompt was auto-enhanced |
| finalPrompt | The enhanced prompt used (only if enhanced) |
Example Request
curl -X POST https://api.iconcraft.app/api/public \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"action": "generate",
"prompt": "zen garden with lotus flower",
"style": "frosted-glass"
}'ideasGenerate icon prompt ideas from an app description.
Cost: $0.05 per request
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | Must be "ideas" |
| description | string | Yes | Description of your app (max 1000 chars) |
| style | string | No | "default" | "minimal" | "clean-3d" | "frosted-glass" |
| highlights | boolean | No | Add [[]] markers around main elements (default: false) e.g. "modern app icon featuring a [[serene lotus flower]]..." |
Response
{
"suggestions": [
"modern app icon featuring a serene lotus flower...",
"modern app icon featuring gentle ripples in calm water...",
"modern app icon featuring a peaceful cloud formation..."
],
"promptSummary": [
"serene lotus on purple gradient",
"calm water ripples with soft glow",
"peaceful cloud with gentle highlights"
]
}| suggestions | Array of 3 ready-to-use prompts |
| promptSummary | Short descriptions of each prompt |
Example Request
curl -X POST https://api.iconcraft.app/api/public \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"action": "ideas",
"description": "A meditation app for busy professionals",
"style": "minimal"
}'Errors
| Code | Description |
|---|---|
| 400 | Bad Request — Missing or invalid parameters |
| 401 | Unauthorized — Invalid or missing API key |
| 402 | Payment Required — Insufficient credits |
| 405 | Method Not Allowed — Use POST only |
| 500 | Internal Error — Request failed, credits refunded |
Error response
{
"error": "Insufficient credits.",
"required": 0.25,
"available": 0.10,
"message": "This action costs $0.25. You have $0.10 credits."
}