# Kwiki AI API

> Generate AI images programmatically

## Quick Start

POST https://kwikiai.com/api/v1/generate
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "prompt": "your image description",
  "quality": "fast",
  "style": "realistic"
}

## Parameters

- prompt (string, required): Image description, max 1000 chars
- quality ("fast" | "hires", optional): fast=1 credit, hires=2 credits. Default: "fast"
- style ("realistic" | "anime" | "nude", optional): Visual style. "nude" enables selfie mode. Default: "realistic"
- appearance (object, optional): Physical traits for nude style. See Appearance Traits below.
- snap_caption (boolean | object, optional): Add Snapchat-style caption (nude style only). Use true for random, or {text, position}

## Appearance Traits (for style: "nude")

All fields are optional. Most accept any string for custom values—only gender and age are strictly validated.

- gender: "female" | "male" | "trans" (strictly validated, default: "female")
- ethnicity: string (suggestions: caucasian, asian, black, latina, arab, indian, mixed, etc.)
- age: 18-70 integer (strictly validated)
- hair_style: string (suggestions: straight, bangs, curly, bun, ponytail, pixie cut, etc.)
- hair_color: string (suggestions: brunette, blonde, black, redhead, pink, silver, etc.)
- eye_color: string (suggestions: brown, blue, green, hazel, amber, etc.)
- body_type: string (suggestions: skinny, athletic, average, curvy, petite, thick, etc.)
- breast_size: string (suggestions: small, medium, large, extra large, perky, etc.)

## Response

Success:
{
  "id": "gen_abc12345",
  "status": "completed",
  "type": "t2i",
  "image_url": "https://cdn.kwikiai.com/...",
  "credits_used": 1,
  "created_at": "2025-12-25T10:30:00Z"
}

Failure (HTTP 503):
{
  "error": "generation_failed",
  "message": "Generation timed out. Please try again."
}

The API uses standard HTTP status codes:
- 200 = Success, response contains image_url and credits_used
- 503 = Generation failed, response contains error and message

Credits are only charged on successful generations. If generation fails, you are not charged.

## Error Codes

- missing_api_key (401): No API key provided
- invalid_api_key (401): API key invalid or revoked
- invalid_request (400): Request body is not valid JSON
- validation_error (400): Invalid request body
- insufficient_credits (402): Not enough credits
- content_blocked (403): Content blocked by moderation
- rate_limited (429): Too many requests
- internal_error (500): Unexpected server error
- generation_failed (503): Service temporarily unavailable

## Rate Limits

- 10 requests/minute
- 100 requests/hour

## Credits

- Fast: 1 credit/image
- Hires: 2 credits/image
- Free tier: 5 credits/day

## Coming Soon

- Character Consistency: Maintain the same character across multiple generations using reference images.
- Image-to-Image: Transform existing images with AI using style transfer and guided editing.
- Video Generation: Generate short AI videos from text prompts or animate still images.
- Image Editing: Inpaint, outpaint, and edit specific regions of images with AI.
- Batch Generation: Generate multiple images in a single API call with variations.
- Async Mode & Webhooks: Submit jobs and receive results via webhook for long-running generations.

## Links

- API Docs: https://kwikiai.com/api-docs
- Get API Key: https://kwikiai.com/account
- Pricing: https://kwikiai.com/pricing