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 Key | Label | Description |
|---|---|---|
free | Free | No style constraints, prompt only |
mrbeast-viral | MrBeast Viral | High energy, bright colors, expressive faces |
reaction-shocked | Reaction Shocked | Dramatic reactions, bold text, eye-catching |
before-after | Before/After | Split comparison, transformation reveal |
challenge-experiment | Challenge | Action shots, suspense, outcome teasing |
gaming-esports | Gaming | Neon colors, dynamic action, game elements |
tech-review | Tech Review | Clean product shots, modern aesthetic |
vlog-travel | Vlog/Travel | Scenic backgrounds, personal connection |
tutorial-educational | Tutorial | Clear visuals, step indicators, helpful |
cinematic-film | Cinematic | Movie poster style, dramatic lighting |
dramatic-intense | Dramatic | High contrast, intense emotions |
mystery-dark | Mystery | Dark tones, intrigue, suspense |
luxury-premium | Luxury | Elegant, premium feel, sophisticated |
office | Cozy Office | Tidy desk, warm light, text-ready composition |
youtube-studio | YouTube Studio | Creator studio setup, ring light, professional |
Using Presets
When creating a thumbnail, specify a preset using thepresetKey parameter:
{
"prompt": "Excited reaction to new iPhone announcement",
"presetKey": "tech-review",
"personId": "your-person-id"
}Preset vs Template
| Method | Description | Best For |
|---|---|---|
presetKey | AI-interpreted style guidelines | Quick generation with a specific vibe |
templateId | Exact visual reference | Matching a specific thumbnail style |
{
"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
| Status | Name | Description |
|---|---|---|
400 | Bad Request | Invalid request body or parameters |
401 | Unauthorized | Missing or invalid API key |
402 | Payment Required | Insufficient credits |
403 | Forbidden | Access denied to resource |
404 | Not Found | Resource doesn't exist |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Server Error | Server-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"]
}
}- Missing required fields
- Invalid field types
- Values outside allowed ranges
- Using both
personIdandpersonName
401 Unauthorized
Returned when authentication fails.{
"success": false,
"error": "Unauthorized"
}- Missing
x-api-keyheader - Invalid or expired API key
- Malformed Authorization header
402 Payment Required
Returned when you don't have enough credits.{
"success": false,
"error": "Insufficient credits"
}403 Forbidden
Returned when you don't have access to a resource.{
"success": false,
"error": "Project does not belong to your organization"
}- 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"
}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"
}Validation Rules Reference
Thumbnails API
| Field | Rules |
|---|---|
prompt | Required, 3-2000 characters |
personId | Optional, valid UUID |
personName | Optional, max 100 characters |
presetKey | Optional, must be valid preset key |
templateId | Optional, valid UUID |
styleReferenceUrl | Optional, valid URL |
youtubeUrl | Optional, valid YouTube URL |
contentImages | Optional, max 5 items |
title | Optional, max 200 characters |
projectName | Optional, max 100 characters |
Advanced Options
| Field | Rules |
|---|---|
variations | 1, 2, 3, or 4 |
faceExpression | neutral, happy, surprised, excited, serious, confident, keep-original |
textPosition | top, center, bottom, none, keep-original |
negativePrompt | Max 500 characters |
clothingStyle | casual, professional, sporty, elegant, streetwear, keep-original |
faceEnhancement | subtle, normal, enhanced, keep-original |
backgroundBlur | 0-100 |
Persons API
| Field | Rules |
|---|---|
name | Required, 1-100 characters |
description | Optional, max 500 characters |
imageIds | Optional, array of UUIDs |
Add Images to Person
| Field | Rules |
|---|---|
imageIds | Required, 1-10 valid UUIDs |
Need Help?
If you encounter issues not covered here:- Check the API documentation for correct usage
- Verify your API key is valid and has proper permissions
- Review the error response details for specific field issues
- Contact support for persistent problems
Include the full error response when contacting support for faster resolution.