代码初始化

model/dto/audio/audio_dto.go

@@ -1,11 +1,15 @@
 package audio
 
+import "github.com/gogf/gf/v2/frame/g"
+
 // TranscribeReq 语音转文字请求（JSON body / URL 方式）
 type TranscribeReq struct {
-	VideoURLs []string `json:"video_urls" v:"required#视频URL列表不能为空" dc:"视频URL列表"`
-	Model     string   `json:"model" dc:"whisper模型(tiny/base/small/medium)" d:"medium"`
-	Language  string   `json:"language" dc:"语言(zh/en/ja)" d:"zh"`
-	Threshold float64  `json:"threshold" dc:"场景检测阈值(0.1-0.5)" d:"0.3"`
+	g.Meta      `path:"/transcribe" method:"post" tags:"音频转写" summary:"语音转文字(异步)" dc:"创建异步语音转文字任务,返回taskId"`
+	VideoURLs   []string `json:"video_urls" v:"required#视频URL列表不能为空" dc:"视频URL列表"`
+	Model       string   `json:"model" dc:"whisper模型(tiny/base/small/medium)" d:"medium"`
+	Language    string   `json:"language" dc:"语言(zh/en/ja)" d:"zh"`
+	Threshold   float64  `json:"threshold" dc:"场景检测阈值(0.1-0.5)" d:"0.3"`
+	CallbackURL string   `json:"callback_url" dc:"任务完成后的回调地址(可选)，成功后POST结果到此URL"`
 }
 
 // TranscribeRes 语音转文字响应

model/dto/audio/task_dto.go

@@ -0,0 +1,130 @@
+package audio
+
+import (
+	"gitea.com/red-future/common/beans"
+	"github.com/gogf/gf/v2/frame/g"
+)
+
+// CreateTaskRes 创建任务响应
+type CreateTaskRes struct {
+	TaskID string `json:"taskId" dc:"任务ID"`
+}
+
+// ---------- 获取任务详情 ----------
+
+// GetTaskReq 获取任务详情请求
+type GetTaskReq struct {
+	g.Meta `path:"/{taskId}" method:"get" tags:"音频转写" summary:"查询任务详情" dc:"根据taskId查询任务详情和明细"`
+	TaskID string `json:"taskId" dc:"任务ID"`
+}
+
+// GetTaskRes 获取任务详情响应
+type GetTaskRes struct {
+	TaskInfo   TranscribeTaskItem         `json:"taskInfo" dc:"任务信息"`
+	DetailList []TranscribeTaskDetailItem `json:"detailList" dc:"明细列表(每视频一条)"`
+}
+
+// TranscribeTaskItem 任务批次项
+type TranscribeTaskItem struct {
+	ID           int64   `json:"id,string" dc:"数据库ID"`
+	TaskID       string  `json:"taskId" dc:"任务ID"`
+	Status       string  `json:"status" dc:"任务状态"`
+	Progress     int     `json:"progress" dc:"进度0-100"`
+	TotalFiles   int     `json:"totalFiles" dc:"文件总数"`
+	SuccessFiles int     `json:"successFiles" dc:"成功文件数"`
+	FailFiles    int     `json:"failFiles" dc:"失败文件数"`
+	Model        string  `json:"model" dc:"whisper模型"`
+	Language     string  `json:"language" dc:"语言"`
+	Threshold    float64 `json:"threshold" dc:"场景检测阈值"`
+	InputType    string  `json:"inputType" dc:"输入类型"`
+	InputData    string  `json:"inputData" dc:"输入数据"`
+	FileNames    string  `json:"fileNames" dc:"文件名列表"`
+	CallbackURL  string  `json:"callbackUrl" dc:"回调地址"`
+	Result       string  `json:"result,omitempty" dc:"完整的处理结果JSON(成功后返回)"`
+	ErrorMessage string  `json:"errorMessage" dc:"错误信息(失败后返回)"`
+	CreatedAt    int64   `json:"createdAt" dc:"创建时间戳"`
+	UpdatedAt    int64   `json:"updatedAt" dc:"更新时间戳"`
+}
+
+// TranscribeTaskDetailItem 任务明细项(每视频)
+type TranscribeTaskDetailItem struct {
+	ID              int64  `json:"id,string" dc:"明细ID"`
+	TaskID          string `json:"taskId" dc:"任务ID"`
+	FileIndex       int    `json:"fileIndex" dc:"文件序号"`
+	FileName        string `json:"fileName" dc:"文件名"`
+	TranscribedText string `json:"transcribedText" dc:"语音识别文字"`
+	Scenes          string `json:"scenes" dc:"分镜分析JSON"`
+	AudioSize       int64  `json:"audioSize" dc:"音频文件大小"`
+	AudioDuration   string `json:"audioDuration" dc:"音频时长"`
+	Model           string `json:"model" dc:"whisper模型"`
+	Language        string `json:"language" dc:"语言代码"`
+	ErrorMessage    string `json:"errorMessage" dc:"错误信息"`
+}
+
+// ---------- 获取任务进度 ----------
+
+// GetProgressReq 获取任务进度请求
+type GetProgressReq struct {
+	g.Meta `path:"/{taskId}/progress" method:"get" tags:"音频转写" summary:"查询任务进度" dc:"查询任务的当前处理进度"`
+	TaskID string `json:"taskId" dc:"任务ID"`
+}
+
+// GetProgressRes 获取任务进度响应
+type GetProgressRes struct {
+	TaskID   string `json:"taskId" dc:"任务ID"`
+	Status   string `json:"status" dc:"任务状态"`
+	Progress int    `json:"progress" dc:"进度0-100"`
+}
+
+// ---------- 任务列表 ----------
+
+// ListTaskReq 获取任务列表请求
+type ListTaskReq struct {
+	g.Meta `path:"/tasks" method:"get" tags:"音频转写" summary:"查询任务列表" dc:"分页查询任务列表,可按状态筛选"`
+	*beans.Page
+	Status string `json:"status" dc:"按状态筛选"`
+}
+
+// ListTaskRes 获取任务列表响应
+type ListTaskRes struct {
+	List  []TranscribeTaskItem `json:"list" dc:"任务列表"`
+	Total int                  `json:"total" dc:"总数"`
+}
+
+// ---------- 回调通知结构 ----------
+
+// CallbackPayload 回调通知内容
+type CallbackPayload struct {
+	TaskID       string                     `json:"taskId" dc:"任务ID"`
+	Status       string                     `json:"status" dc:"任务状态"`
+	TotalFiles   int                        `json:"totalFiles" dc:"文件总数"`
+	SuccessFiles int                        `json:"successFiles" dc:"成功文件数"`
+	FailFiles    int                        `json:"failFiles" dc:"失败文件数"`
+	Result       string                     `json:"result,omitempty" dc:"完整的处理结果JSON"`
+	ErrorMessage string                     `json:"errorMessage,omitempty" dc:"错误信息"`
+	DetailList   []TranscribeTaskDetailItem `json:"detailList" dc:"明细列表"`
+}
+
+// ---------- 任务处理结果结构(用于result JSONB) ----------
+
+// TaskResult 单任务处理结果
+type TaskResult struct {
+	Results []TaskResultItem `json:"results" dc:"处理结果列表"`
+}
+
+// TaskResultItem 单视频处理结果
+type TaskResultItem struct {
+	FileName string         `json:"fileName" dc:"文件名"`
+	Result   *TaskResultDTO `json:"result,omitempty" dc:"识别结果"`
+	Error    string         `json:"error,omitempty" dc:"错误信息"`
+}
+
+// TaskResultDTO 识别结果详情(对外输出，隐藏内部路径)
+type TaskResultDTO struct {
+	Text          string           `json:"text" dc:"识别文本"`
+	Model         string           `json:"model" dc:"使用的模型"`
+	Language      string           `json:"language" dc:"语言"`
+	AudioSize     int64            `json:"audioSize" dc:"音频文件大小(字节)"`
+	AudioDuration string           `json:"audioDuration" dc:"音频时长"`
+	Scenes        *SceneSummaryDTO `json:"scenes,omitempty" dc:"分镜分析"`
+}