# gt: General Translation CLI tool: gt api
URL: https://generaltranslation.com/zh/docs/cli/reference/commands/api.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 发起经过认证的原始请求，或查看内置的 General Translation API 契约。gt api 命令的 API 参考。

当你需要直接访问某个端点，又不想为项目引入 HTTP 客户端时，可以使用 `gt api`。它还可以列出内置的 API 操作，或打印单个操作的契约，无需加载完整的 OpenAPI 规范。

## 概览 [#overview]

```bash
npx gt api [endpoint] [options]
```

传入端点路径 (例如 `/v2/project/info/PROJECT_ID`) 即可发送请求。不指定端点而直接使用 `--list`，可查看所有可用操作；也可以通过 `--spec` 传入操作 ID、规范路径或具体的请求路径，以查看范围更小的接口契约。

## 工作原理 [#how-it-works]

* 优先使用通过 `--api-key` 或 `GT_API_KEY` 显式指定的密钥，否则使用已保存的登录信息 (参见[身份验证优先级](/docs/cli/guides/configuring#credentials)) 。
* 从 `--project-id`、`gt.config.json` 或 `GT_PROJECT_ID` 解析项目 ID。
* 将请求发送到配置的 `baseUrl`，其默认值为 `https://api.gtx.dev`。
* 将原始响应体写入标准输出，遇到网络故障或 HTTP 429/5xx 响应时不会重试。
* 若响应状态码非 2xx，则将摘要写入标准错误并以状态码 1 退出。

如果 `gt.config.json` 提供的项目 ID 与 `--project-id` 或环境变量中的不一致，命令会在发送请求前中止。若只有选项和环境变量提供了不同的 ID，则以选项为准。

`--list` 会为每个内置操作输出一行以制表符分隔的内容，依次为：方法、路径、操作 ID 和摘要。指定端点时，`--spec` 会先按 操作 ID 查找，再按完全匹配的规范路径查找，最后将具体的请求路径与路径参数进行匹配。它会解析筛选后输出中的 schema 引用，并保留被引用的组件和安全方案。递归的 schema 引用则保留为 `$ref` 值。

## 选项 [#flags]

| 参数                      | 说明                                                              | 类型        | 可选 | 默认值                     |
| ----------------------- | --------------------------------------------------------------- | --------- | -- | ----------------------- |
| `-X, --method <method>` | HTTP 方法：`GET`、`HEAD`、`POST`、`PUT`、`PATCH`、`DELETE` 或 `OPTIONS`。 | `string`  | 是  | `GET`                   |
| `--input <file>`        | 从文件读取请求体；设为 `-` 时从标准输入读取。                                       | `string`  | 是  | —                       |
| `-H, --header <header>` | 添加一个 `Key: Value` 请求头。可重复使用以添加多个请求头。                            | `string`  | 是  | —                       |
| `-i, --include`         | 在响应体之前输出响应状态和响应头。                                               | `boolean` | 是  | `false`                 |
| `--spec`                | 打印内置的 OpenAPI 3.1 规范；若指定了端点，则仅输出与该端点相关的部分。                      | `boolean` | 是  | `false`                 |
| `--list`                | 打印所有内置的 API 操作，每行以制表符分隔，依次输出方法、路径、操作 ID 和摘要字段。                  | `boolean` | 是  | `false`                 |
| `-c, --config <path>`   | `gt.config.json` 的路径。可省略 `.json` 后缀。                            | `string`  | 是  | 自动解析                    |
| `--api-key <key>`       | 显式指定工具密钥，覆盖默认值。                                                 | `string`  | 是  | `GT_API_KEY`，未设置时使用登录凭据 |
| `--project-id <id>`     | 覆盖项目 ID。                                                        | `string`  | 是  | 配置文件或 `GT_PROJECT_ID`   |

`--list` 和 `--spec` 可离线使用，无需登录凭据、API Key、项目 ID 或有效的翻译设置。二者不能同时使用。如果针对特定端点的规范查找未匹配到任何操作，命令将以状态码 1 退出，并提示使用 `--list`。

## 示例 [#examples]

```bash
# 保存随已安装的 CLI 依赖项一起打包的 API 快照
npx gt api --spec > openapi.json

# 列出内置的操作
npx gt api --list

# 按操作 ID 或具体请求路径打印单个操作
npx gt api --spec getProjectInfo
npx gt api --spec /v2/project/info/PROJECT_ID

# 使用已保存的登录信息或显式指定的密钥读取项目信息
npx gt api /v2/project/info/PROJECT_ID

# 发送 JSON 请求体，并包含响应元数据
npx gt api /v2/project/info/PROJECT_ID \
  --method POST \
  --header "Content-Type: application/json" \
  --input update.json \
  --include

# 从标准输入读取请求体
printf '{"defaultLocale":"fr"}' |
  npx gt api /v2/project/info/PROJECT_ID \
    --method POST \
    --header "Content-Type: application/json" \
    --input -
```

## 其他说明 [#notes]

* `--spec` 会打印已安装的规范快照，而不会获取当前托管的规范。
* 按路径查找时，会打印匹配规范路径上的所有方法。`--method` 选项不会过滤规范输出。
* 该命令会跳过 CLI 对文件和区域设置的校验，因此即使翻译设置无效，也不会阻止原始 API 请求的发送。
* 可通过 [OpenAPI 参考](/docs/platform/openapi/overview) 查找端点路径、权限、请求字段和响应 schema。

### 版本历史

| 版本       | 变更                                            |
| -------- | --------------------------------------------- |
| `2.25.0` | 新增 `--list`，以及针对单个端点的 `--spec <endpoint>` 输出。 |
| `2.20.0` | 新增 `gt api`，支持发送原始请求和输出完整规范。                  |

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.