# 获取文件列表

> 通用

分页查询指定服务类型的文件列表

## 请求地址

`GET https://api.modelverse.cn/v1/chanjing/files`

## 请求参数

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| service | query | string | Yes | 文件用途筛选 |
| page | query | integer | No | 页码，默认 1 |
| size | query | integer | No | 每页数量，默认 20 |

## 响应

- **200** — 文件列表获取成功
- **400** — 
- **401** — 

## OpenAPI 定义

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "ModelVerse 蝉镜文件管理 API",
    "description": "蝉镜文件管理接口，用于上传和管理数字人、对口型视频等所需的文件资源。\n\n**文件上传流程：**\n1. 调用 `POST /v1/chanjing/files/create_upload` 创建上传任务\n2. 根据返回的 `upload_type` 进行上传：\n   - `single`: 使用 `upload_url` 直接 PUT 上传\n   - `multipart`: 按分片顺序 PUT 上传到各分片的 `upload_url`\n3. 分片上传完成后，调用 `POST /v1/chanjing/files/complete` 完成合并\n4. 使用返回的 `chanjing_file_id` 提交任务\n\n**Service 类型说明：**\n- `customised_person` - 定制数字人\n- `prompt_audio` - 口音转换音色素材\n- `make_video_audio` - 嘴形驱动音频\n- `make_video_background` - 视频合成-背景素材\n- `lip_sync_video` - 对口型视频\n- `lip_sync_audio` - 对口型音频\n- `ai_creation` - AI创作\n",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API 服务器"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/chanjing/files/create_upload": {
      "post": {
        "summary": "创建上传任务",
        "description": "创建文件上传任务，根据文件大小自动判断使用普通上传或分片上传。\n- ≤10MB：返回普通上传地址\n- >10MB：返回分片上传信息\n",
        "operationId": "createChanjingUploadTask",
        "tags": [
          "蝉镜文件管理"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUploadRequest"
              },
              "examples": {
                "singleUpload": {
                  "summary": "普通上传（≤10MB）",
                  "value": {
                    "service": "lip_sync_video",
                    "filename": "test_video.mp4",
                    "file_size": 5242880
                  }
                },
                "multipartUpload": {
                  "summary": "分片上传（>10MB）",
                  "value": {
                    "service": "lip_sync_video",
                    "filename": "large_video.mp4",
                    "file_size": 52428800
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "上传任务创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/SingleUploadResponse"
                    },
                    {
                      "$ref": "#/components/schemas/MultipartUploadResponse"
                    }
                  ]
                },
                "examples": {
                  "singleUpload": {
                    "summary": "普通上传响应",
                    "value": {
                      "id": "5a31046b0df853c6eb972e24ef5fe6f2",
                      "upload_type": "single",
                      "upload_url": "https://chanjing-prod.oss-cn-shanghai.aliyuncs.com/xxx?OSSAccessKeyId=...",
                      "chanjing_file_id": "ea10fde334914dd4ba2ac3cd4d3ac4dc",
                      "full_path": "https://res.chanjing.cc/chanjing/res/37/person/trained/customised_person_example.mp4",
                      "headers": {
                        "Content-Type": "video/mp4"
                      },
                      "mime_type": "video/mp4",
                      "expires_at": 1704070800
                    }
                  },
                  "multipartUpload": {
                    "summary": "分片上传响应",
                    "value": {
                      "id": "5a31046b0df853c6eb972e24ef5fe6f2",
                      "upload_type": "multipart",
                      "upload_id": "0002-4F6B3A4B8A7D",
                      "chanjing_file_id": "921d1db5355c4ccb84d9dbe787d10095",
                      "full_path": "https://res.chanjing.cc/chanjing/res/37/person/trained/customised_person_example.mp4",
                      "mime_type": "video/mp4",
                      "headers": {
                        "Content-Type": "video/mp4"
                      },
                      "part_size": 10485760,
                      "part_count": 3,
                      "parts": [
                        {
                          "part_number": 1,
                          "size": 10485760,
                          "upload_url": "https://chanjing-prod.oss-cn-shanghai.aliyuncs.com/part1?..."
                        },
                        {
                          "part_number": 2,
                          "size": 10485760,
                          "upload_url": "https://chanjing-prod.oss-cn-shanghai.aliyuncs.com/part2?..."
                        },
                        {
                          "part_number": 3,
                          "size": 5242880,
                          "upload_url": "https://chanjing-prod.oss-cn-shanghai.aliyuncs.com/part3?..."
                        }
                      ],
                      "expires_at": 1784196000
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/chanjing/files/complete": {
      "post": {
        "summary": "完成分片上传",
        "description": "所有分片上传完成后，调用此接口通知服务器合并分片。\n仅分片上传模式需要调用此接口。\n",
        "operationId": "completeChanjingMultipartUpload",
        "tags": [
          "蝉镜文件管理"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompleteUploadRequest"
              },
              "example": {
                "upload_id": "2BE130641D284A2C90A277E7732DAFA2"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "分片合并成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompleteUploadResponse"
                },
                "example": {
                  "id": "df71e8a5189bc2908497c5ef2b0ba254",
                  "chanjing_file_id": "e284db4d95de4220afe78132158156b5",
                  "full_path": "https://res.chanjing.cc/chanjing/res/37/person/trained/customised_person_example.mp4",
                  "status": 0
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v1/chanjing/files/{id}": {
      "get": {
        "summary": "获取文件详情",
        "description": "查询指定文件的详细信息和状态",
        "operationId": "getChanjingFileDetail",
        "tags": [
          "蝉镜文件管理"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "文件ID（chanjing_file_id）",
            "schema": {
              "type": "string"
            },
            "example": "ea10fde334914dd4ba2ac3cd4d3ac4dc"
          }
        ],
        "responses": {
          "200": {
            "description": "文件详情获取成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileDetailResponse"
                },
                "example": {
                  "id": "5a31046b0df853c6eb972e24ef5fe6f2",
                  "chanjing_file_id": "ea10fde334914dd4ba2ac3cd4d3ac4dc",
                  "service": "lip_sync_video",
                  "bytes": 5242880,
                  "create_time": 1704067200,
                  "file_path": "https://res.chanjing.cc/chanjing/res/35551/lip_sync/video/xxx.mp4",
                  "status": 1,
                  "msg": ""
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "summary": "删除文件",
        "description": "删除指定的文件",
        "operationId": "deleteChanjingFile",
        "tags": [
          "蝉镜文件管理"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "文件ID（chanjing_file_id）",
            "schema": {
              "type": "string"
            },
            "example": "ea10fde334914dd4ba2ac3cd4d3ac4dc"
          }
        ],
        "responses": {
          "200": {
            "description": "文件删除成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteFileResponse"
                },
                "example": {
                  "id": "746355542a2e96c1e8a56b8b91f561b6",
                  "chanjing_file_id": "ea10fde334914dd4ba2ac3cd4d3ac4dc",
                  "deleted": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/chanjing/files": {
      "get": {
        "summary": "获取文件列表",
        "description": "分页查询指定服务类型的文件列表",
        "operationId": "listChanjingFiles",
        "tags": [
          "蝉镜文件管理"
        ],
        "parameters": [
          {
            "name": "service",
            "in": "query",
            "required": true,
            "description": "文件用途筛选",
            "schema": {
              "type": "string",
              "enum": [
                "customised_person",
                "prompt_audio",
                "make_video_audio",
                "make_video_background",
                "lip_sync_video",
                "lip_sync_audio",
                "ai_creation"
              ]
            },
            "example": "lip_sync_video"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "页码，默认 1",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "description": "每页数量，默认 20",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "文件列表获取成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileListResponse"
                },
                "example": {
                  "id": "df71e8a5189bc2908497c5ef2b0ba254",
                  "data": [
                    {
                      "chanjing_file_id": "e284db4d95de4220afe78132158156b5",
                      "service": "customised_person",
                      "bytes": 0,
                      "create_time": 1753239619,
                      "file_path": "https://www.chanjing.cc/chanjing/res/37/person/trained/customised_person_1753239619_ea65d88474ba4501b8f72903cdf5d3af.mp4",
                      "status": 1,
                      "msg": ""
                    }
                  ],
                  "total_count": 1,
                  "page": 1,
                  "size": 10,
                  "has_more": false
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "API Key 认证，格式：Bearer {api_key}"
      }
    },
    "schemas": {
      "CreateUploadRequest": {
        "type": "object",
        "required": [
          "service",
          "filename",
          "file_size"
        ],
        "properties": {
          "service": {
            "type": "string",
            "description": "文件用途",
            "enum": [
              "customised_person",
              "prompt_audio",
              "make_video_audio",
              "make_video_background",
              "lip_sync_video",
              "lip_sync_audio",
              "ai_creation"
            ]
          },
          "filename": {
            "type": "string",
            "description": "文件名，包含扩展名"
          },
          "file_size": {
            "type": "integer",
            "format": "int64",
            "description": "文件大小（字节），≤10MB使用普通上传，>10MB使用分片上传"
          }
        }
      },
      "SingleUploadResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "蝉镜请求的 trace_id"
          },
          "upload_type": {
            "type": "string",
            "enum": [
              "single"
            ],
            "description": "上传类型"
          },
          "upload_url": {
            "type": "string",
            "description": "普通上传地址（PUT请求）"
          },
          "chanjing_file_id": {
            "type": "string",
            "description": "蝉镜文件ID（提交任务时使用）"
          },
          "full_path": {
            "type": "string",
            "description": "文件最终可访问地址"
          },
          "headers": {
            "type": "object",
            "description": "上传时需要携带的请求头"
          },
          "mime_type": {
            "type": "string",
            "description": "文件的 MIME 类型"
          },
          "expires_at": {
            "type": "integer",
            "description": "上传地址过期时间（Unix时间戳）"
          }
        }
      },
      "MultipartUploadPart": {
        "type": "object",
        "properties": {
          "part_number": {
            "type": "integer",
            "description": "分片序号"
          },
          "size": {
            "type": "integer",
            "format": "int64",
            "description": "分片大小（字节）"
          },
          "upload_url": {
            "type": "string",
            "description": "分片上传地址"
          }
        }
      },
      "MultipartUploadResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "蝉镜请求的 trace_id"
          },
          "upload_type": {
            "type": "string",
            "enum": [
              "multipart"
            ],
            "description": "上传类型"
          },
          "upload_id": {
            "type": "string",
            "description": "分片上传任务ID"
          },
          "chanjing_file_id": {
            "type": "string",
            "description": "蝉镜文件ID"
          },
          "full_path": {
            "type": "string",
            "description": "文件最终可访问地址"
          },
          "mime_type": {
            "type": "string",
            "description": "文件的 MIME 类型"
          },
          "headers": {
            "type": "object",
            "description": "上传时需要携带的请求头"
          },
          "part_size": {
            "type": "integer",
            "description": "分片大小（字节）"
          },
          "part_count": {
            "type": "integer",
            "description": "分片数量"
          },
          "parts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MultipartUploadPart"
            },
            "description": "分片列表"
          },
          "expires_at": {
            "type": "integer",
            "description": "上传地址过期时间（Unix时间戳）"
          }
        }
      },
      "CompleteUploadRequest": {
        "type": "object",
        "required": [
          "upload_id"
        ],
        "properties": {
          "upload_id": {
            "type": "string",
            "description": "创建上传时返回的 upload_id"
          }
        }
      },
      "CompleteUploadResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "蝉镜请求的 trace_id"
          },
          "chanjing_file_id": {
            "type": "string",
            "description": "蝉镜文件ID"
          },
          "full_path": {
            "type": "string",
            "description": "文件最终可访问地址"
          },
          "status": {
            "type": "integer",
            "description": "文件状态：\n- 0: 完成合并，等待异步内容审核\n- 1: 文件可用\n- 98: 内容安全检测失败\n- 99: 标记删除\n- 100: 已清理\n"
          }
        }
      },
      "FileDetailResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "蝉镜请求的 trace_id"
          },
          "chanjing_file_id": {
            "type": "string",
            "description": "蝉镜文件ID"
          },
          "service": {
            "type": "string",
            "description": "文件用途"
          },
          "bytes": {
            "type": "integer",
            "format": "int64",
            "description": "文件大小（字节）"
          },
          "create_time": {
            "type": "integer",
            "description": "创建时间（Unix时间戳）"
          },
          "file_path": {
            "type": "string",
            "description": "文件访问地址"
          },
          "status": {
            "type": "integer",
            "description": "文件状态：\n- 0: 完成合并，等待异步内容审核\n- 1: 文件可用\n- 98: 内容安全检测失败\n- 99: 标记删除\n- 100: 已清理\n"
          },
          "msg": {
            "type": "string",
            "description": "状态说明"
          }
        }
      },
      "DeleteFileResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "蝉镜请求的 trace_id"
          },
          "chanjing_file_id": {
            "type": "string",
            "description": "蝉镜文件ID"
          },
          "deleted": {
            "type": "boolean",
            "description": "是否删除成功"
          }
        }
      },
      "FileListItem": {
        "type": "object",
        "properties": {
          "chanjing_file_id": {
            "type": "string",
            "description": "蝉镜文件ID"
          },
          "service": {
            "type": "string",
            "description": "文件用途"
          },
          "bytes": {
            "type": "integer",
            "format": "int64",
            "description": "文件大小（字节）"
          },
          "create_time": {
            "type": "integer",
            "description": "创建时间（Unix时间戳）"
          },
          "file_path": {
            "type": "string",
            "description": "文件访问地址"
          },
          "status": {
            "type": "integer",
            "description": "文件状态"
          },
          "msg": {
            "type": "string",
            "description": "状态说明"
          }
        }
      },
      "FileListResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "蝉镜请求的 trace_id"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FileListItem"
            },
            "description": "文件列表"
          },
          "total_count": {
            "type": "integer",
            "description": "总文件数"
          },
          "page": {
            "type": "integer",
            "description": "当前页码"
          },
          "size": {
            "type": "integer",
            "description": "每页数量"
          },
          "has_more": {
            "type": "boolean",
            "description": "是否有更多数据"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "错误码"
              },
              "message": {
                "type": "string",
                "description": "错误信息"
              }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "请求参数错误",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "invalid_request",
                "message": "service is required"
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "认证失败",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "missing token"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "资源不存在",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "file not found"
              }
            }
          }
        }
      },
      "InternalError": {
        "description": "服务器内部错误",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "internal_error",
                "message": "complete multipart upload failed"
              }
            }
          }
        }
      }
    }
  }
}
```