Back to Details

rawugc-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

RawUGC API

RawUGC API

Procedural knowledge for agents to call the RawUGC API. All requests require an API key from the RawUGC dashboard, passed via environment variable.
供Agent调用RawUGC API的流程说明。所有请求都需要从RawUGC控制台获取API密钥，通过环境变量传入。

Authentication

认证

  • Environment variable: Read the API key from 
    RAWUGC_API_KEY
    . The key is created in the RawUGC dashboard and must be kept secret; do not hardcode or log it.
  • Header: Send on every request: 
    Authorization: Bearer <value of RAWUGC_API_KEY>
    .
  • If 
    RAWUGC_API_KEY
    is missing or empty, inform the user they must set it and obtain a key from the RawUGC dashboard.
  • 环境变量：从
    RAWUGC_API_KEY
    读取API密钥。该密钥在RawUGC控制台中创建，必须保密，请勿硬编码或记录日志。
  • 请求头：所有请求都需要携带：
    Authorization: Bearer <value of RAWUGC_API_KEY>
    。
  • 如果
    RAWUGC_API_KEY
    缺失或为空，请告知用户必须设置该变量，并且从RawUGC控制台获取密钥。

Base URL

基础URL

  • Production: 
    https://rawugc.com/api/v1
  • All paths below are relative to this base.
  • 生产环境：
    https://rawugc.com/api/v1
  • 下文所有路径都基于该基础URL拼接。

API Versioning

API版本控制

RawUGC uses date-based API versioning. The current latest version is 
2026-03-06
.
  • RawUGC-Version
    request header    : Override the version per-request (recommended).
  • API key pinned version: Set when creating the key in the dashboard.
  • Fallback: Latest version (
    2026-03-06
    ) if neither is set.
Always send 
RawUGC-Version: 2026-03-06
in requests to ensure consistent behavior.
RawUGC使用基于日期的API版本控制，当前最新版本为
2026-03-06
。
  • RawUGC-Version
    请求头    ：可以在单个请求中覆盖版本（推荐使用）。
  • API密钥绑定版本：在控制台创建密钥时可以设置固定版本。
  • 兜底规则：如果上述两种都未设置，默认使用最新版本(
    2026-03-06
    )。
建议所有请求都携带
RawUGC-Version: 2026-03-06
请求头，以保证行为一致性。

Video Generation

视频生成

POST /videos/generate

POST /videos/generate

Initiate video generation.
Request body (JSON):
FieldTypeRequiredDescription
model
stringYes
sora-2-text-to-video
, 
sora-2-image-to-video
, 
kling-2.6/motion-control
, 
veo3
, 
veo3_fast
prompt
stringFor text-to-video / veo3Text description (1-5000 chars)
imageUrls
string[]For image-to-video / klingURLs, max 10. Veo3/veo3_fast accept up to 2 optional images.
videoUrls
string[]For klingURLs, max 1. Required for 
kling-2.6/motion-control
aspectRatio
stringNoSora: 
portrait
/
landscape
. Veo3: 
16:9
/
9:16
/
Auto
nFrames
stringNo
"10"
or 
"15"
(Sora only)
selectedCharacter
stringNoCharacter username (e.g. 
rawugc.mia
)
characterOrientation
stringNo
image
or 
video
(kling only)
mode
stringNo
720p
or 
1080p
(kling only)
Response (201): 
videoId
, 
model
, 
status
, 
creditsUsed
, 
newBalance
, 
estimatedCompletionTime
, 
createdAt
.
发起视频生成任务。
请求体(JSON)：
字段类型必填说明
model
string是
sora-2-text-to-video
, 
sora-2-image-to-video
, 
kling-2.6/motion-control
, 
veo3
, 
veo3_fast
prompt
string文生视频/veo3必填文本描述，长度1-5000字符
imageUrls
string[]图生视频/kling必填图片URL列表，最多10个。Veo3/veo3_fast最多支持2张可选参考图片。
videoUrls
string[]kling必填视频URL列表，最多1个。
kling-2.6/motion-control
模型必填。
aspectRatio
string否Sora可选值：
portrait
/
landscape
。Veo3可选值：
16:9
/
9:16
/
Auto
nFrames
string否
"10"
或 
"15"
（仅Sora支持）
selectedCharacter
string否角色用户名，例如
rawugc.mia
characterOrientation
string否
image
或 
video
（仅kling支持）
mode
string否
720p
或 
1080p
（仅kling支持）
响应(201)：返回
videoId
, 
model
, 
status
, 
creditsUsed
, 
newBalance
, 
estimatedCompletionTime
, 
createdAt
。

GET /videos/:videoId

GET /videos/:videoId

Get video status. Returns 
videoId
, 
status
, 
model
, 
prompt
, 
creditsUsed
, 
url
(when completed), 
createdAt
, 
completedAt
, 
failCode
, 
failMessage
, 
versions
(edit history array).
获取视频生成状态。返回
videoId
, 
status
, 
model
, 
prompt
, 
creditsUsed
, 
url
（生成完成后返回）, 
createdAt
, 
completedAt
, 
failCode
, 
failMessage
, 
versions
（编辑历史数组）。

GET /videos

GET /videos

List videos. Query: 
status
, 
limit
(1-100, default 50), 
page
. Returns 
videos
array + 
pagination
.
获取视频列表。查询参数：
status
, 
limit
(1-100，默认50), 
page
。返回
videos
数组 + 
pagination
分页信息。

POST /videos/captions

POST /videos/captions

Add styled captions to a completed video. Costs 1 credit.
FieldTypeRequiredDescription
videoId
stringYesVideo identifier (vid_xxx)
language
stringNoLanguage code (e.g. 
en
). Defaults to auto-detect
Response (200): 
videoId
, 
url
, 
version
, 
operation
, 
creditsUsed
.
为已生成完成的视频添加样式字幕，消耗1点数。
字段类型必填说明
videoId
string是视频ID，格式为vid_xxx
language
string否语言代码，例如
en
，默认自动检测
响应(200)：返回
videoId
, 
url
, 
version
, 
operation
, 
creditsUsed
。

POST /videos/overlay

POST /videos/overlay

Add text overlay to a completed video.
FieldTypeRequiredDescription
videoId
stringYesVideo identifier (vid_xxx)
text
stringYesOverlay text (1-500 chars)
position
stringNo
top
, 
center
, or 
bottom
fontSize
integerNo8-200 pixels
topBottomMargin
integerNo0-500 pixels
strokeThickness
numberNo0-10
Response (200): 
videoId
, 
url
, 
version
, 
operation
, 
creditsUsed
.
为已生成完成的视频添加文字叠加层。
字段类型必填说明
videoId
string是视频ID，格式为vid_xxx
text
string是叠加文字内容，长度1-500字符
position
string否位置：
top
(顶部), 
center
(居中), 或
bottom
(底部)
fontSize
integer否字号，8-200像素
topBottomMargin
integer否上下边距，0-500像素
strokeThickness
number否文字描边厚度，0-10
响应(200)：返回
videoId
, 
url
, 
version
, 
operation
, 
creditsUsed
。

Image Generation

图片生成

POST /images/generate

POST /images/generate

Generate AI images using Nano Banana models. Async -- poll GET /images/:imageId.
FieldTypeRequiredDescription
model
stringYes
nano-banana-2
(text-to-image, 4 credits) or 
google/nano-banana-edit
(image editing, 2 credits)
prompt
stringYesText description or edit instruction (1-20000 chars)
imageUrls
string[]For editingSource images. Required for 
google/nano-banana-edit
. Optional for 
nano-banana-2
(reference images, max 14).
aspectRatio
stringNoFor 
nano-banana-2
: 
1:1
, 
16:9
, 
9:16
, 
auto
, etc.
imageSize
stringNoFor 
google/nano-banana-edit
: 
1:1
, 
16:9
, 
9:16
, 
auto
, etc.
resolution
stringNoFor 
nano-banana-2
: 
1K
, 
2K
, 
4K
outputFormat
stringNo
png
, 
jpeg
, 
jpg
googleSearch
booleanNoUse Google Web Search grounding (
nano-banana-2
only)
Response (201): 
imageId
, 
model
, 
status
, 
creditsUsed
, 
newBalance
, 
estimatedCompletionTime
, 
createdAt
.
使用Nano Banana模型生成AI图片，异步任务，需要轮询GET /images/:imageId获取结果。
字段类型必填说明
model
string是
nano-banana-2
（文生图，消耗4点数） 或 
google/nano-banana-edit
（图片编辑，消耗2点数）
prompt
string是文本描述或编辑指令，长度1-20000字符
imageUrls
string[]图片编辑必填源图片URL列表，
google/nano-banana-edit
模型必填；
nano-banana-2
可选作为参考图，最多14张。
aspectRatio
string否仅
nano-banana-2
支持：
1:1
, 
16:9
, 
9:16
, 
auto
等
imageSize
string否仅
google/nano-banana-edit
支持：
1:1
, 
16:9
, 
9:16
, 
auto
等
resolution
string否仅
nano-banana-2
支持：
1K
, 
2K
, 
4K
outputFormat
string否输出格式：
png
, 
jpeg
, 
jpg
googleSearch
boolean否启用谷歌网页搜索 grounding（仅
nano-banana-2
支持）
响应(201)：返回
imageId
, 
model
, 
status
, 
creditsUsed
, 
newBalance
, 
estimatedCompletionTime
, 
createdAt
。

GET /images/:imageId

GET /images/:imageId

Get image status. Returns 
imageId
, 
status
, 
model
, 
prompt
, 
url
(when completed), 
imageSize
, 
resolution
, 
outputFormat
, 
creditsUsed
, 
createdAt
, 
completedAt
, 
failCode
, 
failMessage
.
获取图片生成状态。返回
imageId
, 
status
, 
model
, 
prompt
, 
url
（生成完成后返回）, 
imageSize
, 
resolution
, 
outputFormat
, 
creditsUsed
, 
createdAt
, 
completedAt
, 
failCode
, 
failMessage
。

GET /images

GET /images

List images. Query: 
status
, 
limit
(1-100, default 20), 
page
. Returns 
images
array + 
pagination
.
获取图片列表。查询参数：
status
, 
limit
(1-100，默认20), 
page
。返回
images
数组 + 
pagination
分页信息。

Music Generation

音乐生成

POST /music/generate

POST /music/generate

Generate AI music using Suno models. 3 credits per generation. Async -- poll GET /music/:musicId.
FieldTypeRequiredDescription
prompt
stringYesMusic description (1-2000 chars)
model
stringNo
V3_5
, 
V4
, 
V4_5
, 
V4_5PLUS
, 
V4_5ALL
, 
V5
(default: 
V5
)
instrumental
booleanNoInstrumental only, no vocals (default: true)
title
stringNoTrack title (max 200 chars). Enables custom mode with 
style
.
style
stringNoStyle descriptor (max 500 chars, e.g. 
lo-fi hip hop
)
Response (201): 
musicId
, 
model
, 
status
, 
creditsUsed
, 
newBalance
, 
estimatedCompletionTime
, 
createdAt
.
使用Suno模型生成AI音乐，每次生成消耗3点数，异步任务，需要轮询GET /music/:musicId获取结果。
字段类型必填说明
prompt
string是音乐描述，长度1-2000字符
model
string否可选值
V3_5
, 
V4
, 
V4_5
, 
V4_5PLUS
, 
V4_5ALL
, 
V5
，默认
V5
instrumental
boolean否是否仅生成纯音乐无人声，默认true
title
string否曲目名称，最多200字符，搭配
style
字段可启用自定义模式
style
string否风格描述，最多500字符，例如
lo-fi hip hop
响应(201)：返回
musicId
, 
model
, 
status
, 
creditsUsed
, 
newBalance
, 
estimatedCompletionTime
, 
createdAt
。

GET /music/:musicId

GET /music/:musicId

Get music status. Returns 
musicId
, 
status
, 
model
, 
prompt
, 
audioUrl
(when completed), 
albumArtUrl
, 
duration
, 
title
, 
creditsUsed
, 
createdAt
, 
completedAt
, 
failCode
, 
failMessage
.
获取音乐生成状态。返回
musicId
, 
status
, 
model
, 
prompt
, 
audioUrl
（生成完成后返回）, 
albumArtUrl
, 
duration
, 
title
, 
creditsUsed
, 
createdAt
, 
completedAt
, 
failCode
, 
failMessage
。

GET /music

GET /music

List music tracks. Query: 
status
, 
limit
(1-100, default 20), 
page
. Returns 
tracks
array + 
pagination
.
获取音乐列表。查询参数：
status
, 
limit
(1-100，默认20), 
page
。返回
tracks
数组 + 
pagination
分页信息。

Upload

上传

POST /upload

POST /upload

Upload a video or image file. Returns a URL for use in generation requests (
imageUrls
, 
videoUrls
) or 
analyze-video
. Max 100MB.
Request: 
multipart/form-data
with 
file
field. Accepted types: 
video/mp4
, 
video/quicktime
, 
video/webm
, 
image/png
, 
image/jpeg
, 
image/webp
.
Response (200): 
url
, 
contentType
, 
size
.
上传视频或图片文件，返回可用于生成请求（
imageUrls
, 
videoUrls
参数）或
analyze-video
接口的URL，最大支持100MB。
请求：
multipart/form-data
格式，包含
file
字段。支持的文件类型：
video/mp4
, 
video/quicktime
, 
video/webm
, 
image/png
, 
image/jpeg
, 
image/webp
。
响应(200)：返回
url
, 
contentType
, 
size
。

Characters

角色管理

GET /characters

GET /characters

List all available AI characters (built-in + custom). Returns 
characters
array, 
count
, 
adminCount
, 
userCount
.
获取所有可用AI角色（内置+自定义），返回
characters
数组, 
count
, 
adminCount
, 
userCount
。

GET /characters/:characterId

GET /characters/:characterId

Get a character by ID. Returns 
_id
, 
username
, 
displayName
, 
description
, 
videoPreviewUrl
, 
type
(
admin
/
user
), 
isActive
, 
createdAt
, 
updatedAt
.
根据ID获取角色信息，返回
_id
, 
username
, 
displayName
, 
description
, 
videoPreviewUrl
, 
type
(
admin
/
user
), 
isActive
, 
createdAt
, 
updatedAt
。

Personas (CRUD)

用户画像（CRUD）

Personas define target audiences for content plan generation.
  • GET /personas -- List all. Returns 
    personas
    array + 
    count
    .
  • POST /personas -- Create. Body: 
    name
    (required, max 200), 
    description
    (required, max 5000). Returns 
    id
    .
  • GET /personas/:personaId -- Get one.
  • PATCH /personas/:personaId -- Update. Body: 
    name
    , 
    description
    (both optional).
  • DELETE /personas/:personaId -- Delete.
PersonaResponse: 
_id
, 
organizationId
, 
name
, 
description
, 
createdAt
, 
updatedAt
.
用户画像用于定义内容计划生成的目标受众。
  • GET /personas -- 获取所有用户画像，返回
    personas
    数组 + 
    count
    。
  • POST /personas -- 创建用户画像，请求体：
    name
    (必填，最多200字符), 
    description
    (必填，最多5000字符)，返回
    id
    。
  • GET /personas/:personaId -- 获取单个用户画像。
  • PATCH /personas/:personaId -- 更新用户画像，请求体：
    name
    , 
    description
    (均可选)。
  • DELETE /personas/:personaId -- 删除用户画像。
用户画像响应结构：
_id
, 
organizationId
, 
name
, 
description
, 
createdAt
, 
updatedAt
。

Messaging (CRUD)

营销话术（CRUD）

Brand/positioning messaging templates.
  • GET /messaging -- List all. Returns 
    messages
    array + 
    count
    .
  • POST /messaging -- Create. Body: 
    name
    (required, max 200), 
    body
    (required, max 5000). Returns 
    id
    .
  • GET /messaging/:messageId -- Get one.
  • PATCH /messaging/:messageId -- Update. Body: 
    name
    , 
    body
    (both optional).
  • DELETE /messaging/:messageId -- Delete.
MessagingResponse: 
_id
, 
organizationId
, 
name
, 
body
, 
createdAt
, 
updatedAt
.
品牌/定位营销话术模板。
  • GET /messaging -- 获取所有话术模板，返回
    messages
    数组 + 
    count
    。
  • POST /messaging -- 创建话术模板，请求体：
    name
    (必填，最多200字符), 
    body
    (必填，最多5000字符)，返回
    id
    。
  • GET /messaging/:messageId -- 获取单个话术模板。
  • PATCH /messaging/:messageId -- 更新话术模板，请求体：
    name
    , 
    body
    (均可选)。
  • DELETE /messaging/:messageId -- 删除话术模板。
话术模板响应结构：
_id
, 
organizationId
, 
name
, 
body
, 
createdAt
, 
updatedAt
。

Products (CRUD)

产品管理（CRUD）

Products for video generation.
  • GET /products -- List all. Returns 
    products
    array + 
    count
    .
  • POST /products -- Create. Body: 
    name
    (required, max 200), 
    photos
    (required, URL array), 
    description
    (max 1000), 
    messaging
    (max 5000). Returns 
    id
    .
  • GET /products/:productId -- Get one.
  • PATCH /products/:productId -- Update. Body: 
    name
    , 
    description
    , 
    photos
    , 
    messaging
    (all optional).
  • DELETE /products/:productId -- Delete.
ProductResponse: 
_id
, 
name
, 
description
, 
photos
, 
messaging
, 
createdAt
, 
updatedAt
.
用于视频生成的产品信息。
  • GET /products -- 获取所有产品，返回
    products
    数组 + 
    count
    。
  • POST /products -- 创建产品，请求体：
    name
    (必填，最多200字符), 
    photos
    (必填，URL数组), 
    description
    (最多1000字符), 
    messaging
    (最多5000字符)，返回
    id
    。
  • GET /products/:productId -- 获取单个产品信息。
  • PATCH /products/:productId -- 更新产品信息，请求体：
    name
    , 
    description
    , 
    photos
    , 
    messaging
    (均可选)。
  • DELETE /products/:productId -- 删除产品。
产品响应结构：
_id
, 
name
, 
description
, 
photos
, 
messaging
, 
createdAt
, 
updatedAt
。

Styles (CRUD)

风格管理（CRUD）

Video/image creative styles with optional prompt templates.
  • GET /styles -- List all (built-in + custom). Query: 
    type
    (
    video
    /
    image
    ). Returns 
    styles
    array + 
    count
    .
  • POST /styles -- Create. Body: 
    name
    (required, max 200), 
    description
    (max 1000), 
    type
    (
    video
    /
    image
    ), 
    aspectRatio
    (
    portrait
    /
    landscape
    /
    square
    ), 
    promptTemplate
    (max 5000, supports 
    {productName}
    , 
    {messaging}
    , 
    {character}
    placeholders). Returns 
    id
    .
  • GET /styles/:styleId -- Get one.
  • PATCH /styles/:styleId -- Update. All fields optional.
  • DELETE /styles/:styleId -- Delete.
StyleResponse: 
_id
, 
name
, 
description
, 
type
, 
aspectRatio
, 
styleId
, 
promptTemplate
, 
isAdmin
, 
isStandard
.
视频/图片创意风格，支持可选的提示词模板。
  • GET /styles -- 获取所有风格（内置+自定义），查询参数：
    type
    (
    video
    /
    image
    )，返回
    styles
    数组 + 
    count
    。
  • POST /styles -- 创建风格，请求体：
    name
    (必填，最多200字符), 
    description
    (最多1000字符), 
    type
    (
    video
    /
    image
    ), 
    aspectRatio
    (
    portrait
    /
    landscape
    /
    square
    ), 
    promptTemplate
    (最多5000字符，支持
    {productName}
    , 
    {messaging}
    , 
    {character}
    占位符)，返回
    id
    。
  • GET /styles/:styleId -- 获取单个风格信息。
  • PATCH /styles/:styleId -- 更新风格信息，所有字段均可选。
  • DELETE /styles/:styleId -- 删除风格。
风格响应结构：
_id
, 
name
, 
description
, 
type
, 
aspectRatio
, 
styleId
, 
promptTemplate
, 
isAdmin
, 
isStandard
。

Social Scheduling

社交排期

GET /social/accounts

GET /social/accounts

List connected social accounts (max 3 per org). Returns 
accounts
array + 
count
. Each account: 
accountId
, 
platform
(
tiktok
/
instagram
/
youtube
), 
username
, 
displayName
, 
profilePicture
, 
isActive
.
获取已绑定的社交账号，每个组织最多绑定3个，返回
accounts
数组 + 
count
。每个账号信息：
accountId
, 
platform
(
tiktok
/
instagram
/
youtube
), 
username
, 
displayName
, 
profilePicture
, 
isActive
。

POST /social/accounts

POST /social/accounts

Sync connected accounts from the scheduling provider. Returns 
{ success: boolean }
.
从排期服务提供商同步已绑定的账号，返回
{ success: boolean }
。

DELETE /social/accounts/:accountId

DELETE /social/accounts/:accountId

Disconnect a social account. Returns 
{ success: boolean }
.
解绑社交账号，返回
{ success: boolean }
。

POST /social/posts

POST /social/posts

Schedule, draft, or immediately publish a video to social media.
FieldTypeRequiredDescription
videoUrl
stringYesURL of video to post
accountIds
string[]YesTarget account IDs
mode
stringYes
schedule
, 
draft
, or 
now
scheduledFor
integerFor scheduleUnix timestamp (ms)
timezone
stringNoIANA timezone (default: 
UTC
)
content
stringNoCaption (max 2200 chars)
videoId
stringNoRawUGC video ID to link
publishToInbox
booleanNoSend to TikTok Creator Inbox
tiktokPrivacyLevel
stringNo
SELF_ONLY
, 
PUBLIC_TO_EVERYONE
, 
MUTUAL_FOLLOW_FRIENDS
, 
FOLLOWER_OF_CREATOR
tiktokAllowComment
booleanNoAllow TikTok comments
tiktokAllowDuet
booleanNoAllow TikTok duets
tiktokAllowStitch
booleanNoAllow TikTok stitches
tiktokCommercialContentType
stringNo
none
, 
brand_organic
, 
brand_content
Response (201): SocialPost object.
排期、存草稿或立即发布视频到社交媒体。
字段类型必填说明
videoUrl
string是要发布的视频URL
accountIds
string[]是目标发布账号ID列表
mode
string是发布模式：
schedule
(定时发布), 
draft
(存草稿), 或
now
(立即发布)
scheduledFor
integer定时发布必填Unix时间戳（毫秒）
timezone
string否IANA时区，默认
UTC
content
string否帖子文案，最多2200字符
videoId
string否关联的RawUGC视频ID
publishToInbox
boolean否是否发送到TikTok创作者 inbox
tiktokPrivacyLevel
string否TikTok隐私等级：
SELF_ONLY
, 
PUBLIC_TO_EVERYONE
, 
MUTUAL_FOLLOW_FRIENDS
, 
FOLLOWER_OF_CREATOR
tiktokAllowComment
boolean否是否允许TikTok评论
tiktokAllowDuet
boolean否是否允许TikTok合拍
tiktokAllowStitch
boolean否是否允许TikTok剪接
tiktokCommercialContentType
string否TikTok商业内容类型：
none
, 
brand_organic
, 
brand_content
响应(201)：返回SocialPost对象。

GET /social/posts

GET /social/posts

List posts. Query: 
fromDate
(ms), 
toDate
(ms), 
includeDrafts
(boolean). Returns 
posts
array + 
count
.
获取帖子列表，查询参数：
fromDate
(毫秒), 
toDate
(毫秒), 
includeDrafts
(布尔值)，返回
posts
数组 + 
count
。

GET /social/posts/:postId

GET /social/posts/:postId

Get a post.
获取单个帖子信息。

PATCH /social/posts/:postId

PATCH /social/posts/:postId

Update a post. Body: 
content
, 
scheduledFor
, 
timezone
, 
accountIds
(at least one field required).
更新帖子信息，请求体：
content
, 
scheduledFor
, 
timezone
, 
accountIds
(至少填写一个字段)。

DELETE /social/posts/:postId

DELETE /social/posts/:postId

Delete a post. Returns 
{ success: boolean }
.
删除帖子，返回
{ success: boolean }
。

POST /social/posts/:postId/reschedule

POST /social/posts/:postId/reschedule

Reschedule a post. Body: 
scheduledFor
(required, ms), 
timezone
.
重新排期帖子，请求体：
scheduledFor
(必填，毫秒), 
timezone
。

POST /social/posts/:postId/publish

POST /social/posts/:postId/publish

Immediately publish a draft post.
SocialPost: 
postId
, 
platforms
, 
status
(
draft
/
scheduled
/
published
/
failed
), 
scheduledFor
, 
timezone
, 
content
, 
videoUrl
, 
createdAt
, 
publishedAt
.
立即发布草稿帖子。
SocialPost结构：
postId
, 
platforms
, 
status
(
draft
/
scheduled
/
published
/
failed
), 
scheduledFor
, 
timezone
, 
content
, 
videoUrl
, 
createdAt
, 
publishedAt
。

Viral Library

爆款库

GET /viral-library/videos/:videoId

GET /viral-library/videos/:videoId

Get a viral library video with full AI analysis (hooks, keyframes, performance insights). Returns ViralLibraryVideo.
获取爆款库视频的完整AI分析结果（钩子、关键帧、表现洞察），返回ViralLibraryVideo对象。

GET /viral-library/search

GET /viral-library/search

Semantic search across analyzed videos. Query: 
q
(required, natural language), 
limit
(1-50, default 20). Returns 
results
(array of 
{ video, score }
), 
query
, 
total
.
在已分析的视频中进行语义搜索，查询参数：
q
(必填，自然语言查询), 
limit
(1-50，默认20)，返回
results
(
{ video, score }
数组), 
query
, 
total
。

Research

内容调研

POST /scrape-tiktok

POST /scrape-tiktok

Scrape TikTok videos. Costs 3 credits.
FieldTypeRequiredDescription
query
stringYesSearch keyword, hashtag, or query (max 500)
mode
stringNo
keyword
, 
hashtag
, 
search
(default: 
keyword
)
limit
integerNo1-10 (default: 10)
Response (200): 
scrapeId
(use with content-plans), 
count
, 
videos
(array with 
id
, 
url
, 
author
, 
description
, 
stats
, 
duration
, 
hashtags
, 
thumbnail
, 
videoUrl
).
爬取TikTok视频，消耗3点数。
字段类型必填说明
query
string是搜索关键词、话题标签或查询内容，最多500字符
mode
string否搜索模式：
keyword
(关键词), 
hashtag
(话题标签), 
search
(综合搜索)，默认
keyword
limit
integer否返回数量1-10，默认10
响应(200)：返回
scrapeId
（可用于内容计划生成）, 
count
, 
videos
（数组包含
id
, 
url
, 
author
, 
description
, 
stats
, 
duration
, 
hashtags
, 
thumbnail
, 
videoUrl
）。

POST /content-plans

POST /content-plans

Generate a content plan from scraped videos. Costs 3 credits.
FieldTypeRequiredDescription
scrapeId
stringYesFrom scrape-tiktok response
brief
stringYesContent plan goals (max 5000)
Response (200): 
planId
, 
scrapeId
, 
brief
, 
topWins
, 
gapsToTest
, 
blueprints
(array with 
category
, 
strategy
, 
evidence
, 
contentIdeas
).
基于爬取的视频生成内容计划，消耗3点数。
字段类型必填说明
scrapeId
string是来自scrape-tiktok接口返回的ID
brief
string是内容计划目标，最多5000字符
响应(200)：返回
planId
, 
scrapeId
, 
brief
, 
topWins
, 
gapsToTest
, 
blueprints
（数组包含
category
, 
strategy
, 
evidence
, 
contentIdeas
）。

GET /content-plans

GET /content-plans

List all content plans. Returns 
plans
array + 
count
.
获取所有内容计划，返回
plans
数组 + 
count
。

POST /analyze-video

POST /analyze-video

Analyze any video URL (social links or direct URLs). Costs 1 credit. Max 150MB.
FieldTypeRequiredDescription
videoUrl
stringYesVideo URL to analyze
prompt
stringNoCustom analysis prompt (max 5000)
Response (200): 
summary
, 
hook
, 
keyframes
(array with 
timestamp
, 
type
, 
description
, 
visual
, 
audio
, 
text
), 
durationSeconds
, 
tags
, 
whyItPerformed
, 
attributesToCopy
, 
hooksToTest
.
分析任意视频URL（社交链接或直链），消耗1点数，最大支持150MB。
字段类型必填说明
videoUrl
string是要分析的视频URL
prompt
string否自定义分析提示词，最多5000字符
响应(200)：返回
summary
, 
hook
, 
keyframes
（数组包含
timestamp
, 
type
, 
description
, 
visual
, 
audio
, 
text
）, 
durationSeconds
, 
tags
, 
whyItPerformed
, 
attributesToCopy
, 
hooksToTest
。

Errors

错误说明

All error responses use RFC 7807 Problem Details (JSON): 
type
, 
title
, 
status
, 
detail
, 
instance
, 
errors
.
StatusMeaning
400Validation error. Surface 
detail
and 
errors
to user.
401Auth error. Check 
RAWUGC_API_KEY
.
402Insufficient credits. Add credits in dashboard.
403Insufficient scope. API key lacks permissions.
404Resource not found.
429Rate limit exceeded. Check 
X-RateLimit-Reset
header.
500Server error. Retry or contact support.
所有错误响应遵循RFC 7807 Problem Details规范（JSON格式）：
type
, 
title
, 
status
, 
detail
, 
instance
, 
errors
。
状态码含义
400参数校验错误，将
detail
和
errors
信息展示给用户。
401认证错误，检查
RAWUGC_API_KEY
是否正确。
402点数不足，请在控制台充值点数。
403权限不足，API密钥没有对应权限。
404资源不存在。
429触发速率限制，请查看
X-RateLimit-Reset
请求头。
500服务端错误，可重试或联系客服。

Rate Limits

速率限制

  • API Key: 10 req/min. Session: 20 req/min.
  • Headers: 
    X-RateLimit-Limit
    , 
    X-RateLimit-Remaining
    , 
    X-RateLimit-Reset
    (unix timestamp).
  • API密钥维度：10次请求/分钟；会话维度：20次请求/分钟。
  • 响应头包含：
    X-RateLimit-Limit
    , 
    X-RateLimit-Remaining
    , 
    X-RateLimit-Reset
    （Unix时间戳）。

Workflow: Generate then poll

工作流：生成后轮询

  1. Generate: POST to the generation endpoint. Note the returned ID (
    videoId
    /
    imageId
    /
    musicId
    ).
  2. Poll: GET the status endpoint periodically (10-30s). Use exponential backoff.
  3. Finish: When 
    status === 'completed'
    , use the result URL. When 
    failed
    , surface error to user.
  4. Edit (video only): POST to 
    /videos/captions
    or 
    /videos/overlay
    .
For full request/response shapes, see reference.md.
  1. 发起生成：调用生成接口POST请求，记录返回的ID（
    videoId
    /
    imageId
    /
    musicId
    ）。
  2. 轮询状态：定期调用状态查询GET接口（间隔10-30秒），建议使用指数退避策略。
  3. 处理结果：当
    status === 'completed'
    时，使用返回的结果URL；当状态为
    failed
    时，将错误信息展示给用户。
  4. 编辑（仅视频支持）：可调用
    /videos/captions
    或
    /videos/overlay
    接口进行二次编辑。
完整的请求/响应结构请查看reference.md。