# General Translation Platform: 获取文件信息
URL: https://generaltranslation.com/zh/docs/platform/openapi/reference/files/file-info.mdx
---

title: 获取文件信息
description: 查看 General Translation 源文件的元数据、版本、区域设置和翻译状态。Get file information 的 API 参考。

method: POST
---

按引用返回源文件和翻译后的文件的元数据。可在一次请求中查询源文件、翻译后的文件，或同时查询两者。

## 概览 [#overview]

```http
POST https://api2.gtx.dev/v2/project/files/info
```

**权限** `project:files:read` · **速率限制** 默认 (200/分钟) 

无需下载文件内容即可查看文件元数据。要查看单个文件按区域设置划分的翻译进度，请使用 [获取翻译状态](/docs/platform/openapi/reference/files/translation-status)。

## 工作方式 [#how-it-works]

* 提供 `sourceFiles`、`translatedFiles`，或两者都提供。每个列表都会单独解析，并分别在各自的数组中返回。
* 仅返回实际存在的文件；未匹配的引用会被省略，不会报错。
* 响应仅包含元数据 (区域设置、格式、时间戳) ，不包含文件内容。

## 请求 [#request]

### 请求头

| 请求头               | 说明               | 必需 |
| ----------------- | ---------------- | -- |
| `x-gt-api-key`    | 项目或组织 API 密钥。    | 是  |
| `x-gt-project-id` | 项目 ID。使用组织密钥时必需。 | 否  |

### 请求体

**内容类型** `application/json`

| 字段                | 描述           | 类型         | 可选 | 默认值 |
| ----------------- | ------------ | ---------- | -- | --- |
| `sourceFiles`     | 要查找的源文件引用。   | `object[]` | 是  | —   |
| `translatedFiles` | 要查找的翻译后的文件引用。 | `object[]` | 是  | —   |

每个 `sourceFiles` 元素都必须包含 `fileId`、`versionId` 和 `branchId`。每个 `translatedFiles` 元素都必须包含 `fileId`、`versionId`、`branchId` 和 `locale`。所有值均不能为空。

## 响应 [#response]

**状态** `200 OK`

```json title="Response"
{
  "sourceFiles": [
    {
      "branchId": "br_...",
      "fileId": "file_...",
      "versionId": "ver_...",
      "fileName": "en/common.json",
      "fileFormat": "JSON",
      "dataFormat": "JSON",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "publishedAt": null,
      "locales": ["es", "fr"],
      "sourceLocale": "en"
    }
  ],
  "translatedFiles": [
    {
      "branchId": "br_...",
      "fileId": "file_...",
      "versionId": "ver_...",
      "fileFormat": "JSON",
      "dataFormat": "JSON",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "approvedAt": null,
      "publishedAt": null,
      "completedAt": "2026-01-01T00:00:00.000Z",
      "locale": "es"
    }
  ]
}
```

## 错误 [#errors]

| 状态    | 原因                                  |
| ----- | ----------------------------------- |
| `400` | 文件查询无效。                             |
| `401` | 缺少 API Key，或 API Key 无效。            |
| `403` | API Key 缺少 `project:files:read` 权限。 |
| `429` | 超出速率限制。                             |

## 示例 [#example]

```bash
curl -X POST https://api2.gtx.dev/v2/project/files/info \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '{
    "sourceFiles": [
      {
        "fileId": "file_...",
        "versionId": "ver_...",
        "branchId": "br_..."
      }
    ]
  }'
```