youthumb-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

YouThumb API — Thumbnail Generation Skill

YouThumb API — 缩略图生成技能

Automate YouTube thumbnail creation via the YouThumb.ai developer API.

通过YouThumb.ai开发者API自动化生成YouTube缩略图。

Authentication

认证

Get your API key: Log in to YouThumb.ai → User menu → Account → API Key.

Set it as an environment variable:

bash

export YOUTHUMB_API_KEY="your-api-key-here"

All API calls require the header:

x-api-key: $YOUTHUMB_API_KEY

获取你的API密钥： 登录YouThumb.ai → 用户菜单 → 账户 → API Key。

将其设置为环境变量：

bash

export YOUTHUMB_API_KEY="your-api-key-here"

所有API调用都需要携带以下请求头：

x-api-key: $YOUTHUMB_API_KEY

API Reference

API 参考

Base URL:

https://www.youthumb.ai

基础URL：

https://www.youthumb.ai

Endpoints Overview

端点总览

Method	Endpoint	Description
Assets
POST	`/api/assets`	Upload an image
GET	`/api/assets`	List all assets
GET	`/api/assets/:id`	Get asset details
DELETE	`/api/assets/:id`	Delete an asset
Thumbnails
POST	`/api/thumbnails`	Create a project
POST	`/api/thumbnails/:projectId/start`	Start generation (costs credits)
GET	`/api/thumbnails/:projectId/status`	Simple status check
GET	`/api/thumbnails/:projectId/detailed-status`	Status with image URLs
Persons
GET	`/api/persons`	List all persons
POST	`/api/persons`	Create a person
GET	`/api/persons/:id`	Get person details
POST	`/api/persons/:id/images`	Add face images to a person
Other
GET	`/api/templates`	List available templates
GET	`/api/presets`	List available presets

Full API docs: https://www.youthumb.ai/en/docs/developer-api

方法	端点	描述
资源管理
POST	`/api/assets`	上传图片
GET	`/api/assets`	列出所有资源
GET	`/api/assets/:id`	获取资源详情
DELETE	`/api/assets/:id`	删除资源
缩略图管理
POST	`/api/thumbnails`	创建项目
POST	`/api/thumbnails/:projectId/start`	启动生成任务（消耗积分）
GET	`/api/thumbnails/:projectId/status`	简易状态查询
GET	`/api/thumbnails/:projectId/detailed-status`	包含图片URL的详细状态查询
人物管理
GET	`/api/persons`	列出所有人物
POST	`/api/persons`	创建人物
GET	`/api/persons/:id`	获取人物详情
POST	`/api/persons/:id/images`	为人物添加人脸图片
其他
GET	`/api/templates`	列出可用模板
GET	`/api/presets`	列出可用预设

完整API文档： https://www.youthumb.ai/en/docs/developer-api

Workflow

工作流程

Step 1 — Set Up a Person (one-time)

步骤1 — 设置人物（仅需配置一次）

A Person is a face identity used across thumbnails. Upload 3-5 clear photos of the subject.

bash

undefined

人物是跨缩略图使用的人脸身份标识，需要上传3-5张主体的清晰照片。

bash

undefined

Create a person

创建人物

curl -s -X POST "https://www.youthumb.ai/api/persons"
-H "x-api-key: $YOUTHUMB_API_KEY"
-H "Content-Type: application/json"
-d '{"name": "John Creator"}'


Response:
```json
{"success": true, "data": {"id": "uuid-of-person", "name": "John Creator"}}

bash

undefined

curl -s -X POST "https://www.youthumb.ai/api/persons"
-H "x-api-key: $YOUTHUMB_API_KEY"
-H "Content-Type: application/json"
-d '{"name": "John Creator"}'


返回结果：
```json
{"success": true, "data": {"id": "uuid-of-person", "name": "John Creator"}}

bash

undefined

Add face images (base64 encoded)

添加人脸图片（base64编码）

FACE_B64=$(base64 -w0 /path/to/face-photo.jpg) curl -s -X POST "https://www.youthumb.ai/api/persons/PERSON_ID/images"
-H "x-api-key: $YOUTHUMB_API_KEY"
-H "Content-Type: application/json"
-d "{"base64":"$FACE_B64","filename":"face1.jpg","mimeType":"image/jpeg"}"


Upload 3-5 images with different angles and lighting for best results.


为了获得最佳效果，请上传3-5张不同角度、不同光照条件的图片。

Step 2 — Upload Assets (logos, screenshots, icons)

步骤2 — 上传资源（logo、截图、图标）

Assets are visual elements that appear on the thumbnail (logos, screenshots, icons).

bash

undefined

资源是指展示在缩略图上的视觉元素（logo、截图、图标）。

bash

undefined

Upload an image asset

上传图片资源

ICON_B64=$(base64 -w0 /path/to/logo.png) curl -s -X POST "https://www.youthumb.ai/api/assets"
-H "x-api-key: $YOUTHUMB_API_KEY"
-H "Content-Type: application/json"
-d "{"base64":"$ICON_B64","type":"bucket","filename":"logo.png","mimeType":"image/png"}"


Response:
```json
{"success": true, "data": {"id": "uuid", "url": "https://...supabase.co/..."}}

⚠️ Always use
"type": "bucket"
for content assets (logos, screenshots, etc.).

⚠️ Verify the file is a real image before uploading — check with

file /path/to/image.png

. If it returns "HTML document" or anything other than image data, do NOT upload.


返回结果：
```json
{"success": true, "data": {"id": "uuid", "url": "https://...supabase.co/..."}}

⚠️ 内容资源（logo、截图等）必须使用
"type": "bucket"
。

⚠️ 上传前请确认文件是真实图片，可以用

file /path/to/image.png

命令校验。如果返回结果是"HTML document"或者其他非图片数据的描述，请不要上传。

Step 3 — Create a Thumbnail Project

步骤3 — 创建缩略图项目

bash

curl -s -X POST "https://www.youthumb.ai/api/thumbnails" \
  -H "x-api-key: $YOUTHUMB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Person on the left with a confident smirk. @image1 (React logo) floating on the right with blue glow. Clean dark background with subtle teal lighting. No text.",
    "presetKey": "free",
    "projectName": "React Tutorial Thumb",
    "personId": "your-person-uuid",
    "contentImages": [
      {"url": "https://...your-uploaded-asset-url..."}
    ],
    "advancedOptions": {
      "variations": 1,
      "faceExpression": "confident",
      "textPosition": "none"
    }
  }'

Response:

json

{"success": true, "data": {"id": "project-uuid", "status": "draft"}}

bash

curl -s -X POST "https://www.youthumb.ai/api/thumbnails" \
  -H "x-api-key: $YOUTHUMB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Person on the left with a confident smirk. @image1 (React logo) floating on the right with blue glow. Clean dark background with subtle teal lighting. No text.",
    "presetKey": "free",
    "projectName": "React Tutorial Thumb",
    "personId": "your-person-uuid",
    "contentImages": [
      {"url": "https://...your-uploaded-asset-url..."}
    ],
    "advancedOptions": {
      "variations": 1,
      "faceExpression": "confident",
      "textPosition": "none"
    }
  }'

返回结果：

json

{"success": true, "data": {"id": "project-uuid", "status": "draft"}}

Asset References in Prompts (Critical)

提示词中的资源引用（关键）

Reference uploaded assets in your prompt using

@image1

@image2

@image3

etc. They map to the

contentImages

array in order.

@image1 → contentImages[0]
@image2 → contentImages[1]
@image3 → contentImages[2]

Always include
@imageN (description)
in the prompt text. Without this reference, the uploaded image will NOT appear on the thumbnail.

Example:

Subject on the left, confident expression. @image1 (Claude Code logo) prominently displayed center-right with orange glow. @image2 (code screenshot) in the background with glass overlay. Dark cinematic atmosphere.

在提示词中使用

@image1

、

@image2

、

@image3

等格式来引用上传的资源，它们会按顺序对应

contentImages

数组中的元素。

@image1 → contentImages[0]
@image2 → contentImages[1]
@image3 → contentImages[2]

必须在提示词文本中加入
@imageN (描述)
的格式，如果没有这个引用，上传的图片不会出现在生成的缩略图中。

示例：

主体在左侧，表情自信。@image1（Claude Code logo）放在中右侧位置，带有橙色发光效果。@image2（代码截图）放在背景，添加玻璃态覆盖层。整体为深色电影质感氛围。

Content Images Format

内容图片格式

json

{"url": "https://..."}          // By direct URL (preferred)
{"userImageId": "asset-uuid"}   // By uploaded asset ID

Max 5 content images per project.

json

{"url": "https://..."}          // 直接使用URL（推荐）
{"userImageId": "asset-uuid"}   // 使用已上传资源的ID

每个项目最多支持5张内容图片。

Step 4 — Start Generation

步骤4 — 启动生成任务

⚠️ This consumes credits. Always verify the project looks correct before starting.

bash

undefined

⚠️ 该操作会消耗积分，启动前请务必确认项目配置正确。

bash

undefined

Verify the project first

先校验项目配置

curl -s "https://www.youthumb.ai/api/thumbnails/$PROJECT_ID/detailed-status"
-H "x-api-key: $YOUTHUMB_API_KEY"


Check that `contentImages` contains the correct URLs (not empty objects `{}`).

```bash

curl -s "https://www.youthumb.ai/api/thumbnails/$PROJECT_ID/detailed-status"
-H "x-api-key: $YOUTHUMB_API_KEY"


确认`contentImages`中包含正确的URL（不要是空对象`{}`）。

```bash

Start generation

启动生成任务

curl -s -X POST "https://www.youthumb.ai/api/thumbnails/$PROJECT_ID/start"
-H "x-api-key: $YOUTHUMB_API_KEY"


The `start` endpoint optionally accepts `prompt` and `advancedOptions` to override the project config:

```bash
curl -s -X POST "https://www.youthumb.ai/api/thumbnails/$PROJECT_ID/start" \
  -H "x-api-key: $YOUTHUMB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Alternative prompt for this generation run"}'

curl -s -X POST "https://www.youthumb.ai/api/thumbnails/$PROJECT_ID/start"
-H "x-api-key: $YOUTHUMB_API_KEY"


`start`端点可选传入`prompt`和`advancedOptions`参数来覆盖项目的原有配置：

```bash
curl -s -X POST "https://www.youthumb.ai/api/thumbnails/$PROJECT_ID/start" \
  -H "x-api-key: $YOUTHUMB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Alternative prompt for this generation run"}'

Step 5 — Retrieve Results

步骤5 — 获取生成结果

Poll the status until generation completes:

bash

curl -s "https://www.youthumb.ai/api/thumbnails/$PROJECT_ID/detailed-status" \
  -H "x-api-key: $YOUTHUMB_API_KEY"

When

status: "completed"

, download the results from

jobs[].images.results[]

轮询状态接口直到生成完成：

bash

curl -s "https://www.youthumb.ai/api/thumbnails/$PROJECT_ID/detailed-status" \
  -H "x-api-key: $YOUTHUMB_API_KEY"

当返回

status: "completed"

时，就可以从

jobs[].images.results[]

中下载生成结果。

Field Validation Reference

字段校验参考

Thumbnail Project

缩略图项目

Field	Required	Rules
`prompt`	✅ Yes	3-2000 characters
`presetKey`	✅ Yes	Use `"free"`
`personId`	No	UUID — do not combine with `personName`
`personName`	No	Max 100 chars — do not combine with `personId`
`projectName`	No	Max 100 chars
`contentImages`	No	Max 5 items, each `{url?}` or `{userImageId?}`
`title`	No	Max 200 chars
`templateId`	No	UUID
`styleReferenceUrl`	No	Valid URL
`youtubeUrl`	No	Valid URL

字段	必填	规则
`prompt`	✅ 是	3-2000个字符
`presetKey`	✅ 是	请使用 `"free"`
`personId`	否	UUID — 不要和 `personName` 同时使用
`personName`	否	最多100个字符 — 不要和 `personId` 同时使用
`projectName`	否	最多100个字符
`contentImages`	否	最多5项，每项格式为 `{url?}` 或 `{userImageId?}`
`title`	否	最多200个字符
`templateId`	否	UUID
`styleReferenceUrl`	否	合法URL
`youtubeUrl`	否	合法URL

Advanced Options

高级选项

Field	Values	Default
`variations`	1, 2, 3, or 4	1
`faceExpression`	neutral, happy, surprised, excited, serious, confident, keep-original	confident
`textPosition`	top, center, bottom, none, keep-original	none
`negativePrompt`	Max 500 chars	—
`clothingStyle`	casual, professional, sporty, elegant, streetwear, keep-original	keep-original
`faceEnhancement`	subtle, normal, enhanced, keep-original	normal
`backgroundBlur`	0-100	0

字段	可选值	默认值
`variations`	1, 2, 3, 4	1
`faceExpression`	neutral（中性）, happy（开心）, surprised（惊讶）, excited（兴奋）, serious（严肃）, confident（自信）, keep-original（保持原图）	confident（自信）
`textPosition`	top（顶部）, center（居中）, bottom（底部）, none（无）, keep-original（保持原图）	none（无）
`negativePrompt`	最多500个字符	—
`clothingStyle`	casual（休闲）, professional（职业）, sporty（运动）, elegant（优雅）, streetwear（街头风）, keep-original（保持原图）	keep-original（保持原图）
`faceEnhancement`	subtle（轻度）, normal（普通）, enhanced（增强）, keep-original（保持原图）	normal（普通）
`backgroundBlur`	0-100	0

Rate Limits

速率限制

The API has aggressive rate limiting. Important:

Wait 30-45 seconds between calls when you hit a rate limit
A
```
401 Unauthorized
```
response is often a rate limit in disguise, not a real auth error — wait and retry
Do NOT spam retries — use exponential backoff
One request at a time is safest

该API有非常严格的速率限制，请注意：

触发速率限制后请等待30-45秒再发起请求
```
401 Unauthorized
```
响应通常是伪装的速率限制提示，不是真实的认证错误，请等待后重试
不要频繁重试请求，请使用指数退避策略
同一时间只发起一个请求是最安全的做法

Error Codes

错误码

Code	Meaning	Action
400	Bad request	Check required fields and validation rules
401	Invalid/missing API key	Verify your key — or wait (could be rate limit)
402	Insufficient credits	Top up credits at youthumb.ai
403	Access denied	Check account permissions
404	Resource not found	Verify project/person/asset ID
429	Rate limited	Wait 30-45 seconds and retry
500	Server error	Retry after a delay

错误码	含义	处理方式
400	请求参数错误	检查必填字段和校验规则
401	API密钥无效/缺失	校验你的密钥 — 或者等待重试（可能是速率限制）
402	积分不足	前往youthumb.ai充值积分
403	访问被拒绝	检查账户权限
404	资源不存在	校验项目/人物/资源ID
429	触发速率限制	等待30-45秒后重试
500	服务器错误	等待一段时间后重试

Best Practices

最佳实践

Always verify before generating — check
```
detailed-status
```
to confirm assets are correctly linked
Start with 1 variation — each variation costs credits, scale up only when needed
Use
presetKey: "free"
— gives full control over the prompt
Validate images before upload — verify files are actual images (PNG, JPEG), not HTML or SVG
Reference every asset — use
```
@image1 (description)
```
in prompts or the image won't appear
Respect rate limits — the API is strict, space your calls out

For prompt writing tips and examples, see the companion skill: youthumb-prompts.

生成前务必校验配置 — 检查
```
detailed-status
```
返回结果，确认资源已经正确关联
初期先使用1个变体生成 — 每个变体都会消耗积分，确认效果符合预期后再增加变体数量
使用
presetKey: "free"
— 可以完全自定义提示词
上传前校验图片 — 确认文件是真实的图片（PNG、JPEG格式），不是HTML或者SVG
所有资源都要添加引用 — 在提示词中使用
```
@image1 (描述)
```
的格式，否则图片不会出现在生成结果中
遵守速率限制规则 — API的限制非常严格，请控制请求间隔

想要了解提示词编写技巧和示例，请查看配套技能：youthumb-prompts。