PicPuzzle API

Back to PicPuzzle

Developer API Documentation

Introduction

The PicPuzzle API enables programmatic creation of puzzles. This REST API allows applications to create puzzles with images either from a URL or generated via AI based on a text prompt.

Base URL

https://api.picpuzzle.xyz/api

Authentication

Currently, the API is open for use without authentication. Future versions may require API keys for rate limiting and security.

Endpoints

Create Puzzle

Creates a new puzzle with either an AI-generated image or an image from a URL.

POST/puzzles/create

Content-Type: application/json

Request Parameters

ParameterTypeRequiredDescription
image_typestringYesSource of the image: "ai" or "url"
promptstringYes (if image_type="ai")Text prompt for AI image generation
image_urlstringYes (if image_type="url")URL of the image to use for the puzzle
difficultystringYesPuzzle difficulty: "easy", "medium", or "hard"
creatorNamestringYesName of the puzzle creator
messagestringNoOptional message to display with the puzzle
secretMessagestringNoOptional message revealed only when puzzle is solved
notify_emailstringNoEmail to notify when the puzzle is attempted or completed

Example Requests

AI-generated image:

// POST https://api.picpuzzle.xyz/api/puzzles/create
{
  "image_type": "ai",
  "prompt": "A serene mountain lake with snow-capped peaks at sunset",
  "difficulty": "medium",
  "creatorName": "API Demo",
  "message": "Can you solve this puzzle?",
  "secretMessage": "Congratulations on solving this AI-generated puzzle!",
  "notify_email": "creator@example.com"
}

URL image:

// POST https://api.picpuzzle.xyz/api/puzzles/create
{
  "image_type": "url",
  "image_url": "https://example.com/image.jpg",
  "difficulty": "hard",
  "creatorName": "API Demo",
  "message": "This is a challenging puzzle!",
  "secretMessage": "Well done on solving this difficult puzzle!",
  "notify_email": "creator@example.com"
}

Response Format

Success Response (201 Created):

{
  "success": true,
  "message": "Puzzle created successfully",
  "puzzle": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "shareCode": "ABCD1234",
    "shareUrl": "https://picpuzzle.xyz/puzzle/ABCD1234"
  }
}

Important Response Fields

  • id: Unique puzzle identifier
  • shareCode: Short code for sharing
  • shareUrl: Complete URL that can be shared with users to solve the puzzle

Error Responses

Missing Required Parameters (400)

{
  "error": "Missing required fields",
  "required": ["image_type", "creatorName", "difficulty"]
}

Invalid Image Type (400)

{
  "error": "Invalid image_type",
  "message": "image_type must be 'ai' or 'url'"
}

Missing Prompt (400)

{
  "error": "Missing prompt",
  "message": "A prompt is required when image_type is 'ai'"
}

Invalid Difficulty (400)

{
  "error": "Invalid difficulty",
  "validOptions": ["easy", "medium", "hard"]
}

Code Example

JavaScript (Node.js):

const axios = require('axios');

async function createPuzzle() {
  try {
    const response = await axios.post('https://api.picpuzzle.xyz/api/puzzles/create', {
      image_type: 'url',
      image_url: 'https://picsum.photos/800/600', // Random image for testing
      difficulty: 'medium',
      creatorName: 'API Demo',
      message: 'This puzzle was created via the API!',
      secretMessage: 'Congratulations on solving the API-created puzzle!'
    });
    
    console.log('Success! Puzzle created:');
    console.log(`Share URL: ${response.data.puzzle.shareUrl}`);
    return response.data;
  } catch (error) {
    console.error('Error creating puzzle:');
    if (error.response) {
      console.error(`Status: ${error.response.status}`);
      console.error(error.response.data);
    } else {
      console.error(error.message);
    }
  }
}

createPuzzle();

Note: Remember to handle errors appropriately in your production code.

AI Image Generation

The PicPuzzle API leverages X.AI's 'grok-2-image' model for generating high-quality images from text prompts. When using the AI option, provide a descriptive prompt for best results.

Tips for Effective Prompts:

  • Be detailed and specific about what you want in the image
  • Describe style, lighting, and mood for more control
  • Include subject, setting, and any important visual elements
  • Keep prompts clear and focused for best results

Rate Limiting & Future Plans

Currently, there are no rate limits enforced on the API. However, please use the API responsibly. Future versions may include rate limiting, authentication, and additional endpoints for puzzle management.