Skip to main content
POST
Create a thumbnail generation job
Experimental. Subject to change; daily caps apply and the endpoint may be temporarily disabled via a runtime kill switch. Currently published jobType: thumbnail.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
jobType
enum<string>
required

The type of generative job to create. Currently the only published value is thumbnail.

Available options:
thumbnail
sourceUri
string
required

URL of the source video to extract thumbnails from.

Example:

"https://youtube.com/watch?v=..."

referenceImageUri
string

Optional reference image URL. The thumbnail composition draws stylistic cues from this image. Upload via POST /api/upload-links with usecase: 'FreeToolMedia', then pass the returned cdnUrl here.

Example:

"https://cdn.opus.pro/uploads/.../ref.png"

maskImageUri
string

Optional mask image URL for inpainting.

Example:

"https://cdn.opus.pro/uploads/.../mask.png"

prompt
string

Optional text prompt steering the thumbnail composition.

Example:

"punchy red overlay, bold sans-serif title"

Response

201 - application/json
jobId
string
required

The generated job ID. Use it with GET /api/generative-jobs/{jobId} to poll status and fetch results.

Example:

"thumbnail-aB3xR7nQ8z"