Modelink

OpenAPI 参考

Modelink API · 文件

Modelink 文件管理 API，提供文件上传、状态查询与列表等能力，支持多模态对话中的文件引用。所有请求均需通过 Bearer Token 进行身份认证。

版本 1.0.0

列出用户文件

GET
/v1/files

获取当前用户的文件列表。支持按状态过滤和游标分页。

分页使用游标方式，通过 after 参数传入上一页最后一条记录的 ID 来获取下一页数据。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

查询参数

  • Name
    status
    Type
    enum
    Description

    按文件状态过滤

  • Name
    limit
    Type
    integer
    Description

    分页大小，范围 0-100，默认 20

  • Name
    after
    Type
    string
    Description

    游标分页参数，传入上一页最后一条记录的 ID

  • Name
    order
    Type
    enum
    Description

    排序方向，默认按创建时间降序

请求体

暂无请求体

请求

GET/v1/files
curl 'https://api.qnaigc.com/v1/files?status={status}&limit={limit}&after={after}&order={order}' \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json'

响应

object

成功返回文件列表

响应体属性

    • idstring, 必填

      文件唯一标识，格式：qfile-xxxx

    • modelstring

      目标模型 ID

    • created_atinteger<int64>, 必填

      创建时间（Unix 时间戳，秒）

    • synced_atinteger<int64>

      同步完成时间（Unix 时间戳，秒）。仅当 status 为 ready 时有值

    • expires_atinteger<int64>, 必填

      过期时间（Unix 时间戳，秒）

    • file_namestring

      原始文件名

    • file_sizeinteger<int64>

      文件大小（字节）。仅当文件同步完成后有值

    • content_typestring

      MIME 类型。仅当文件同步完成后有值

  • has_moreboolean, 必填

    是否还有更多数据。如果为 true，可使用 last_id 作为 after 参数获取下一页

  • first_idstring

    本页第一条记录的 ID

  • last_idstring

    本页最后一条记录的 ID，可用作下一页请求的 after 参数

响应

application/json
{
  "object": "list",
  "data": [
    {
      "id": "qfile-12345-1705382400-abc123",
      "object": "file",
      "status": "ready",
      "model": "gemini-2.0-flash",
      "created_at": 1705382400,
      "synced_at": 1705382450,
      "expires_at": 1705555200,
      "file_name": "sample.pdf",
      "file_size": 1048576,
      "content_type": "application/pdf"
    },
    {
      "id": "qfile-12345-1705296000-def456",
      "object": "file",
      "status": "expired",
      "model": "gpt-4o",
      "created_at": 1705296000,
      "synced_at": 1705296100,
      "expires_at": 1705468800,
      "file_name": "image.png",
      "file_size": 204800,
      "content_type": "image/png"
    }
  ],
  "has_more": true,
  "first_id": "qfile-12345-1705382400-abc123",
  "last_id": "qfile-12345-1705296000-def456"
}

创建文件上传任务

POST
/v1/files

文件上传

这是一个异步文件上传导入任务。本接口专为 Gemini 模型大文件理解场景 优化。

💡 为什么使用此接口？

Vertex AI 在通过 HTTP 直接传入文件进行理解时，存在 15MB 的硬性限制。对于大于 15MB 的文件（如长视频、高分辨率图像），官方要求必须使用 Google Cloud Storage (GCS) 链接。 本接口旨在简化该流程：您可以提供公开 URL，系统会自动把文件转存至目标云存储并对接 Vertex AI。

接口约束

  • 支持场景：仅适用于 Gemini 模型的大文件（>15MB）多模态理解。
  • 文件大小：最大支持 2GB。
  • 输入来源：source_url 必须是海外公网可访问的 HTTP/HTTPS 地址。私有 Kodo 文件请先生成带有效期的公开访问 URL，再通过 source_url 提交。

调用流程

  1. 提交任务：调用本接口提交 source_url。
  2. 获取 ID：接口立即返回 file_id，任务进入后台异步处理队列。
  3. 检查状态：客户端需轮询 GET /files/{file_id} 接口，直到文件状态变更为 ready 。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

请求体

请求体属性

  • modelstring, 必填

    目标模型 ID，如 gemini-2.0-flash等。 文件将被同步到该模型所需的云存储服务。 同系列模型创建的file_id可以共用。例如 gemini-2.0-flash 模型创建的file_id，gemini-3.0-pro-preview 也调用。

  • source_urlstring<uri>, 必填

    公开可访问的文件 URL（HTTP/HTTPS）。私有 Kodo 文件需先生成带有效期的公开访问 URL。

  • expires_ininteger

    过期时间（秒）。范围：3600（1小时）~ 2592000（30天），默认 172800（48小时）

    default: 172800; minimum: 3600; maximum: 2592000

请求

POST/v1/files
curl https://api.qnaigc.com/v1/files \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gemini-3.0-pro-preview",
  "source_url": "https://aitoken-public.qnaigc.com/example/generate-video/running-man.jpg",
  "expires_in": 172800
}'

响应

object

文件导入任务创建成功

响应体属性

  • idstring, 必填

    文件唯一标识，格式：qfile-xxxx

  • modelstring

    目标模型 ID

  • created_atinteger<int64>, 必填

    创建时间（Unix 时间戳，秒）

  • synced_atinteger<int64>

    同步完成时间（Unix 时间戳，秒）。仅当 status 为 ready 时有值

  • expires_atinteger<int64>, 必填

    过期时间（Unix 时间戳，秒）

  • file_namestring

    原始文件名

  • file_sizeinteger<int64>

    文件大小（字节）。仅当文件同步完成后有值

  • content_typestring

    MIME 类型。仅当文件同步完成后有值

    • codestring, 必填

      错误码

    • messagestring, 必填

      错误描述

    • typestring

      错误类型

    • paramstring

      相关参数名

响应

application/json
{
  "id": "qfile-12345-1770727746152401856-01d742",
  "object": "file",
  "status": "pending",
  "model": "gemini-3.0-pro-preview",
  "created_at": 1770727746,
  "expires_at": 1770900546
}

查询文件状态

GET
/v1/files/{file_id}

根据文件 ID 查询文件的详细信息和当前状态。

状态说明：

  • pending：等待处理
  • uploading：正在上传到目标存储
  • ready：上传完成，可用于推理
  • failed：上传失败，查看 error 字段获取详细信息
  • expired：文件已过期，需要重新创建

🚀 调用示例：从导入到推理

以下展示了当文件处理完成并获得 file_id 后，如何在模型推理接口中使用该文件。

场景：视频理解

假设您已通过本接口上传了一个长视频，并获得了文件 ID：qfile-123-1770719212268100147-e0011b。

请求说明： 在推理接口（Chat/Completions）的 messages 数组中，将 type 指定为 file 或 image_url ，并填入对应的 file_id 或 url。

请求报文 (JSON)：

{
    "stream": false,
    "model": "gemini-3.0-pro-preview",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "这段视频里发生了什么？请详细描述。"
                },
                {
                    "type": "file",
                    "file": {
                        "file_id": "qfile-123-1770719212268100147-e0011b",
                        "format": "video/mp4"
                    }
                }
            ]
        }
    ]
}

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

路径参数

  • Name
    file_id
    Type
    string, 必填
    Description

    文件唯一标识，格式：qfile-{user}-{timestamp}-{nonce}

请求体

暂无请求体

请求

GET/v1/files/{file_id}
curl https://api.qnaigc.com/v1/files/{file_id} \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json'

响应

object

成功返回文件详情

响应体属性

  • idstring, 必填

    文件唯一标识，格式：qfile-xxxx

  • modelstring

    目标模型 ID

  • created_atinteger<int64>, 必填

    创建时间（Unix 时间戳，秒）

  • synced_atinteger<int64>

    同步完成时间（Unix 时间戳，秒）。仅当 status 为 ready 时有值

  • expires_atinteger<int64>, 必填

    过期时间（Unix 时间戳，秒）

  • file_namestring

    原始文件名

  • file_sizeinteger<int64>

    文件大小（字节）。仅当文件同步完成后有值

  • content_typestring

    MIME 类型。仅当文件同步完成后有值

    • codestring, 必填

      错误码

    • messagestring, 必填

      错误描述

    • typestring

      错误类型

    • paramstring

      相关参数名

响应

application/json
{
  "id": "qfile-12345-1705382400-abc123",
  "object": "file",
  "status": "ready",
  "model": "gemini-2.0-flash",
  "created_at": 1705382400,
  "synced_at": 1705382450,
  "expires_at": 1705555200,
  "file_name": "sample.pdf",
  "file_size": 1048576,
  "content_type": "application/pdf"
}

删除文件

DELETE
/v1/files/{file_id}

删除指定的文件记录及其在目标存储中的资源。

删除操作会：

  1. 删除数据库中的文件记录
  2. 尝试删除目标云存储中的文件副本（如果存在）

注意：删除操作不可逆，请谨慎操作。

认证方式

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

路径参数

  • Name
    file_id
    Type
    string, 必填
    Description

    文件唯一标识，格式：qfile-{uid}-{timestamp}-{nonce}

请求体

暂无请求体

请求

DELETE/v1/files/{file_id}
curl https://api.qnaigc.com/v1/files/{file_id} \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json'

响应

object

文件删除成功

响应体属性

  • idstring, 必填

    已删除文件的唯一标识

  • deletedboolean, 必填

    是否已成功删除

响应

application/json
{
  "id": "qfile-12345-1705382400-abc123",
  "object": "file",
  "deleted": true
}

Last updated

© 2026 Modelink. All rights reserved.

构建来自Clarify