API ReferenceThumbnail
Generate Background
Generate only the background image for a thumbnail using AI.
POST /api/v1/thumbnail/generate-background
Generate only the background image for a thumbnail. Useful when you want to compose the thumbnail manually using your own text overlays and elements.
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 background |
manualTitle | string | No | — | Video title for context |
resolution | string | No | — | Output resolution |
platform | string | No | "youtube" | Target platform |
sessionId | string | No | — | Group in an existing session |
overrideTitle | boolean | No | true | Whether to override the auto-detected title |
templateId | string | No | — | Use a saved template |
Example Request
curl -X POST https://api.usesoke.ai/api/v1/thumbnail/generate-background \
-H "Content-Type: application/json" \
-H "X-Soke-Key: sk_live_your_api_key" \
-d '{
"manualTitle": "10 Developer Productivity Hacks",
"manualPrompt": "A clean minimalist desk setup with warm lighting",
"platform": "youtube"
}'Response
Returns the same async job format as Generate Thumbnail. Poll via GET /api/v1/thumbnail/{id}.
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 |