Presets & Error Codes

This page documents the available style presets and common API error codes.

Presets API

Presets are predefined style configurations that guide the AI's visual output. They provide quick access to proven thumbnail styles without needing a template image.

List Presets

GET /api/presets
curl https://youthumb.ai/api/presets \
  -H "x-api-key: your_api_key"

Presets Response

{
  "success": true,
  "data": [
    {
      "key": "mrbeast-viral",
      "label": "MrBeast Viral",
      "emoji": "🔥",
      "description": "High energy, bright colors, expressive faces"
    },
    ...
  ]
}

Available Presets

Preset KeyLabelDescription
freeFreeNo style constraints, prompt only
mrbeast-viralMrBeast ViralHigh energy, bright colors, expressive faces
reaction-shockedReaction ShockedDramatic reactions, bold text, eye-catching
before-afterBefore/AfterSplit comparison, transformation reveal
challenge-experimentChallengeAction shots, suspense, outcome teasing
gaming-esportsGamingNeon colors, dynamic action, game elements
tech-reviewTech ReviewClean product shots, modern aesthetic
vlog-travelVlog/TravelScenic backgrounds, personal connection
tutorial-educationalTutorialClear visuals, step indicators, helpful
cinematic-filmCinematicMovie poster style, dramatic lighting
dramatic-intenseDramaticHigh contrast, intense emotions
mystery-darkMysteryDark tones, intrigue, suspense
luxury-premiumLuxuryElegant, premium feel, sophisticated
officeCozy OfficeTidy desk, warm light, text-ready composition
youtube-studioYouTube StudioCreator studio setup, ring light, professional

Using Presets

When creating a thumbnail, specify a preset using the presetKey parameter:
{
  "prompt": "Excited reaction to new iPhone announcement",
  "presetKey": "tech-review",
  "personId": "your-person-id"
}

Preset vs Template

MethodDescriptionBest For
presetKeyAI-interpreted style guidelinesQuick generation with a specific vibe
templateIdExact visual referenceMatching a specific thumbnail style
You can combine both:
{
  "prompt": "Review of the latest MacBook",
  "presetKey": "tech-review",
  "templateId": "template-uuid",
  "personId": "your-person-id"
}

Error Codes

All API errors follow a consistent format:
{
  "success": false,
  "error": "Error message",
  "details": { ... }
}

HTTP Status Codes

StatusNameDescription
400Bad RequestInvalid request body or parameters
401UnauthorizedMissing or invalid API key
402Payment RequiredInsufficient credits
403ForbiddenAccess denied to resource
404Not FoundResource doesn't exist
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side error

400 Bad Request

Returned when request validation fails.
{
  "success": false,
  "error": "Validation error",
  "details": {
    "prompt": ["String must contain at least 3 character(s)"],
    "personId": ["Invalid uuid"]
  }
}
Common causes:
  • Missing required fields
  • Invalid field types
  • Values outside allowed ranges
  • Using both personId and personName

401 Unauthorized

Returned when authentication fails.
{
  "success": false,
  "error": "Unauthorized"
}
Common causes:
  • Missing x-api-key header
  • Invalid or expired API key
  • Malformed Authorization header

402 Payment Required

Returned when you don't have enough credits.
{
  "success": false,
  "error": "Insufficient credits"
}
Solution: Purchase more credits or upgrade your subscription.

403 Forbidden

Returned when you don't have access to a resource.
{
  "success": false,
  "error": "Project does not belong to your organization"
}
Common causes:
  • Accessing another organization's resources
  • Insufficient permissions

404 Not Found

Returned when a resource doesn't exist.
{
  "success": false,
  "error": "Project not found"
}
{
  "success": false,
  "error": "Person not found"
}
{
  "success": false,
  "error": "Template not found"
}

429 Too Many Requests

Returned when you exceed rate limits.
{
  "success": false,
  "error": "Rate limit exceeded"
}
Solution: Wait before retrying. Implement exponential backoff.
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const waitTime = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

500 Internal Server Error

Returned when something goes wrong on our end.
{
  "success": false,
  "error": "Internal server error"
}
Solution: Retry later. If persistent, contact support.

Validation Rules Reference

Thumbnails API

FieldRules
promptRequired, 3-2000 characters
personIdOptional, valid UUID
personNameOptional, max 100 characters
presetKeyOptional, must be valid preset key
templateIdOptional, valid UUID
styleReferenceUrlOptional, valid URL
youtubeUrlOptional, valid YouTube URL
contentImagesOptional, max 5 items
titleOptional, max 200 characters
projectNameOptional, max 100 characters

Advanced Options

FieldRules
variations1, 2, 3, or 4
faceExpressionneutral, happy, surprised, excited, serious, confident, keep-original
textPositiontop, center, bottom, none, keep-original
negativePromptMax 500 characters
clothingStylecasual, professional, sporty, elegant, streetwear, keep-original
faceEnhancementsubtle, normal, enhanced, keep-original
backgroundBlur0-100

Persons API

FieldRules
nameRequired, 1-100 characters
descriptionOptional, max 500 characters
imageIdsOptional, array of UUIDs

Add Images to Person

FieldRules
imageIdsRequired, 1-10 valid UUIDs

Need Help?

If you encounter issues not covered here:
  1. Check the API documentation for correct usage
  2. Verify your API key is valid and has proper permissions
  3. Review the error response details for specific field issues
  4. Contact support for persistent problems
Include the full error response when contacting support for faster resolution.