API Documentation

Programmatic access to PicShapes image generation

Quick Navigation

Getting Started

1. Create an API Key

Generate your API key from the dashboard. You'll need to be signed in with Google.

Go to API Keys Dashboard →

2. Base URL

https://api.picshapes.com

3. API Key Format

Your API key starts with uk_ followed by 64 hexadecimal characters.

Authentication

Include your API key in the Authorization header as a Bearer token:

curl -H "Authorization: Bearer uk_your_api_key_here" \
  https://api.picshapes.com/api/v1/users/me

Keep your API key secret! Never expose it in client-side code or public repositories.

Rate Limits

Limit Type	Value
Per-minute limit	60 requests
Daily limit	1,000 requests

When rate limited, you'll receive a 429 Too Many Requests response with a retry_after field indicating seconds to wait.

API Endpoints

GET/api/v1/users/me/credits

Check your current credit balance.

Request

curl -H "Authorization: Bearer uk_your_api_key_here" \
  https://api.picshapes.com/api/v1/users/me/credits

Response

{
  "credits": 86,
  "user_id": "550e8400-e29b-41d4-a716-446655440000"
}

GET/api/v1/tiers

Get available quality tiers and their pricing. No authentication required.

Request

curl https://api.picshapes.com/api/v1/tiers

Response

{
  "tiers": {
    "basic": {
      "name": "Basic",
      "max_width": 1024,
      "max_height": 1024,
      "credits": 1
    },
    "pro": {
      "name": "Pro",
      "max_width": 1440,
      "max_height": 1440,
      "credits": 3
    },
    "premium": {
      "name": "Premium",
      "max_width": 1536,
      "max_height": 1536,
      "credits": 5
    }
  }
}

POST/api/v1/jobs

Create an image generation job. Credits are deducted immediately.

Request Body

Field	Type	Required	Description
prompt	string	Yes	Text description of the image to generate
tier	string	No	basic (default), pro, or premium
width	integer	No	Image width (max depends on tier)
height	integer	No	Image height (max depends on tier)
seed	integer	No	Random seed for reproducibility

Request

curl -X POST https://api.picshapes.com/api/v1/jobs \
  -H "Authorization: Bearer uk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a beautiful sunset over mountains, digital art",
    "tier": "basic"
  }'

Response (201 Created)

{
  "id": "8ed8f84c-c9b8-43f4-a8cd-90dec79ada7d",
  "status": "pending",
  "prompt": "a beautiful sunset over mountains, digital art",
  "tier": "basic",
  "width": 1024,
  "height": 1024,
  "steps": 8,
  "created_at": "2025-12-19T22:22:47Z"
}

GET/api/v1/jobs/:id

Check the status of a job. No authentication required.

Job Statuses

pending	Job is queued, waiting for a worker
processing	Worker is generating the image
completed	Image is ready, result_url is available
failed	Generation failed, error_msg contains details

Request

curl https://api.picshapes.com/api/v1/jobs/8ed8f84c-c9b8-43f4-a8cd-90dec79ada7d

Response (Completed)

{
  "id": "8ed8f84c-c9b8-43f4-a8cd-90dec79ada7d",
  "status": "completed",
  "prompt": "a beautiful sunset over mountains, digital art",
  "tier": "basic",
  "width": 1024,
  "height": 1024,
  "result_url": "https://storage.picshapes.com/ai-gen-results/results/8ed8f84c.png",
  "created_at": "2025-12-19T22:22:47Z",
  "completed_at": "2025-12-19T22:23:03Z"
}

GET/api/v1/jobs/:id/result

Get just the result URL. Returns 202 if job is not yet complete.

Request

curl https://api.picshapes.com/api/v1/jobs/8ed8f84c-c9b8-43f4-a8cd-90dec79ada7d/result

Response (200 OK)

{
  "result_url": "https://storage.picshapes.com/ai-gen-results/results/8ed8f84c.png"
}

Response (202 Accepted - Not Ready)

{
  "status": "processing",
  "message": "Job is not completed yet"
}

Complete Workflow Example

Here's a complete bash script that creates a job and polls until completion:

#!/bin/bash
API_KEY="uk_your_api_key_here"
BASE_URL="https://api.picshapes.com"

# 1. Check credits
echo "Checking credits..."
curl -s -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/api/v1/users/me/credits" | jq

# 2. Create job
echo "Creating job..."
JOB_ID=$(curl -s -X POST "$BASE_URL/api/v1/jobs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a robot painting a sunset", "tier": "basic"}' \
  | jq -r '.id')

echo "Job ID: $JOB_ID"

# 3. Poll for completion
echo "Waiting for completion..."
while true; do
  STATUS=$(curl -s "$BASE_URL/api/v1/jobs/$JOB_ID" | jq -r '.status')
  echo "Status: $STATUS"

  if [ "$STATUS" = "completed" ]; then
    RESULT_URL=$(curl -s "$BASE_URL/api/v1/jobs/$JOB_ID" | jq -r '.result_url')
    echo "Done! Image URL: $RESULT_URL"

    # 4. Download image
    curl -s "$RESULT_URL" -o "result.png"
    echo "Saved to result.png"
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Job failed!"
    curl -s "$BASE_URL/api/v1/jobs/$JOB_ID" | jq '.error_msg'
    exit 1
  fi

  sleep 2
done

Error Codes

Status	Code	Description
400	INVALID_TIER	Invalid tier specified
400	TIER_LIMIT_EXCEEDED	Width/height exceeds tier limits
401	INVALID_API_KEY	API key is invalid or expired
402	INSUFFICIENT_CREDITS	Not enough credits for this tier
404	-	Job not found
429	RATE_LIMIT_EXCEEDED	Too many requests, retry after delay
429	DAILY_LIMIT_EXCEEDED	Daily request limit reached

Error Response Format

{
  "error": "Insufficient credits",
  "code": "INSUFFICIENT_CREDITS",
  "credits": 0,
  "credits_needed": 1
}

OpenAPI Specification

A machine-readable OpenAPI 3.0 specification is available for automated tooling and client generation.

Download openapi.yaml

Need help? Visit the API Keys Dashboard to manage your keys.