API Documentation

Integrate AI image generation into your applications

Overview

The GirlGeneratorAI API lets you generate AI images programmatically. All requests use JSON and require authentication via API key.

Base URLhttps://girlgenerator.app

Authentication

All API requests require a Bearer token. Create an API key in Settings → API Keys.

Header

Authorization: Bearer YOUR_API_KEY

Generate Image

Submit an image generation task. The response includes a task ID for polling.

POST /api/v1/generate

Parameters

scenestringrequired

"text-to-image" or "image-to-image"

promptstringrequired

Text prompt describing the image (max 2000 chars)

aspect_ratiostring

Optional. One of: auto, 1:1, 3:2, 2:3, 9:16, 16:9, 3:4, 4:3. Default: auto

image_inputstring[]

Required for image-to-image. Array of reference image URLs

Response

201 Created

{
  "task_id": "abc123",
  "status": "pending",
  "credits_used": 1,
  "credits_remaining": 12762
}

Examples

cURL

curl -X POST https://girlgenerator.app/api/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scene": "text-to-image",
    "prompt": "a cute anime girl with blue hair, detailed portrait",
    "aspect_ratio": "1:1"
  }'

Python

import requests

response = requests.post(
    "https://girlgenerator.app/api/v1/generate",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "scene": "text-to-image",
        "prompt": "a cute anime girl with blue hair, detailed portrait",
        "aspect_ratio": "1:1",
    },
)
data = response.json()
print(data["task_id"])  # Use this to poll for results

JavaScript (fetch)

const response = await fetch("https://girlgenerator.app/api/v1/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    scene: "text-to-image",
    prompt: "a cute anime girl with blue hair, detailed portrait",
    aspect_ratio: "1:1",
  }),
});

const data = await response.json();
console.log(data.task_id); // Use this to poll for results

Query Task

Poll a task to check its status and retrieve generated images.

GET /api/v1/tasks/task_id

Response

Pending / Processing

{
  "task_id": "abc123",
  "status": "processing"
}

Success

{
  "task_id": "abc123",
  "status": "success",
  "images": [
    "https://example.com/generated-image.png"
  ]
}

Failed

{
  "task_id": "abc123",
  "status": "failed",
  "error": "Generation failed due to content policy."
}

Status Values

pendingTask is queued

processingImage is being generated

successGeneration complete, images available

failedGeneration failed, error message available

Polling Example

Python

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://girlgenerator.app"

# 1. Submit generation task
resp = requests.post(
    f"{BASE_URL}/api/v1/generate",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"scene": "text-to-image", "prompt": "a cute anime girl"},
)
task_id = resp.json()["task_id"]

# 2. Poll until complete
while True:
    result = requests.get(
        f"{BASE_URL}/api/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
    ).json()

    if result["status"] == "success":
        print("Images:", result["images"])
        break
    elif result["status"] == "failed":
        print("Error:", result["error"])
        break

    time.sleep(5)  # Wait 5 seconds before polling again

Error Codes

All errors follow this format:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable description."
  }
}

HTTP Status	Error Code	Description
401	`unauthorized`	Missing or invalid API key
403	`insufficient_credits`	Not enough credits for this operation
404	`task_not_found`	Task does not exist or belongs to another user
422	`invalid_params`	Request validation failed
429	`rate_limit_exceeded`	Too many requests (limit: 10/min)
500	`internal_error`	Server error

Rate Limits & Credits

⚡

10 requests per minute per API key

💰

Credit cost varies by model: 1–3 credits per generation. See the model list for details.

🛈

API and web usage share the same credit balance.