Generate Thumbnail
Generate AI-powered thumbnails using DALL-E. Returns an async job.
POST /api/v1/thumbnail/generate
Generate an AI-powered thumbnail for your video using DALL-E. This is an async operation — it returns a job that you can poll via GET /api/v1/thumbnail/{id}.
Credits: 4 per request
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
videoUrl | string | No | — | YouTube video URL for context |
manualPrompt | string | No | — | Custom prompt for the thumbnail |
manualTitle | string | No | — | Video title for context (used if no videoUrl) |
colorGrading | string | Yes* | — | Color grading preset: None, Warm, Cool, Cinematic, Vintage, Desaturated, or Neon |
layoutType | string | Yes* | — | Layout type: TextLeft, TextRight, TextCenter, TextBottom, or FullBleed |
resolution | string | No | "1280x720" | Output resolution: 1280x720 (landscape) or 1080x1920 (portrait/shorts) |
platform | string | No | "youtube" | Target platform |
sessionId | string | No | — | Group multiple generations in a session |
templateId | string | No | — | Use a saved template |
Provide either videoUrl (to auto-extract title/context) or manualTitle/manualPrompt.
* colorGrading and layoutType are optional when a templateId is provided — the template's values will be used.
Recommended: Create a thumbnail template in the dashboard with your preferred styling (font, colors, overlay, resolution, layout, color grading, accent detection) and pass only the templateId when generating. This gives you consistent, branded thumbnails without needing to specify all parameters on every request.
Example Request
Using a template (recommended):
curl -X POST https://api.usesoke.ai/api/v1/thumbnail/generate \
-H "Content-Type: application/json" \
-H "X-Soke-Key: sk_live_your_api_key" \
-d '{
"manualTitle": "10 Developer Productivity Hacks",
"manualPrompt": "A developer at a clean desk with multiple monitors showing code",
"templateId": "your-template-id",
"platform": "youtube"
}'Without a template:
curl -X POST https://api.usesoke.ai/api/v1/thumbnail/generate \
-H "Content-Type: application/json" \
-H "X-Soke-Key: sk_live_your_api_key" \
-d '{
"manualTitle": "10 Developer Productivity Hacks",
"manualPrompt": "A developer at a clean desk with multiple monitors showing code",
"colorGrading": "Cinematic",
"layoutType": "TextCenter",
"resolution": "1080x1920",
"platform": "youtube"
}'Response
{
"success": true,
"data": {
"id": "thumb_abc123",
"status": "processing",
"sessionId": "session_xyz789"
},
"meta": {
"platform": "youtube",
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"processing_time_ms": 150
}
}Polling for Results
curl "https://api.usesoke.ai/api/v1/thumbnail/thumb_abc123" \
-H "X-Soke-Key: sk_live_your_api_key"When complete, the response includes the generated image URL and editor state.
Error Codes
| Code | Status | Description |
|---|---|---|
BAD_REQUEST | 400 | Missing required fields |
RATE_LIMIT_EXCEEDED | 429 | Rate limit exceeded |
INSUFFICIENT_CREDITS | 402 | Not enough credits |
PLATFORM_NOT_IMPLEMENTED | 501 | Platform not yet supported |