SDK 使用指南

计费说明

OpenAPI 调用本身不收取额外费用，计费仅在翻译任务实际执行时按 Credits 扣减。计费规则与控制台完全一致。

上传文件（UploadTranslationFile）不产生费用，仅预估 Credits 消耗
提交翻译任务（SubmitTranslationTask）后开始计费
取消任务后，冻结的 Credits 全额返还

警告

提交翻译任务前请确保账户 Credits 余额充足。可提前参考 UploadTranslationFile 返回的 CreditsAvailable 字段，最终以提交结果为准。余额不足时，SubmitTranslationTask 会返回 Credits.NotEnough。

详细的计费方式和扣费顺序请参阅：产品计费

产品信息

配置项	值
Endpoint	`realtranslationagent.aliyuncs.com`
Product Code	RealTranslationAgent
API 版本	2026-06-22

安装 SDK

Java

// 在 pom.xml 中添加依赖：
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>realtranslationagent20260622</artifactId>
    <version>1.0.0</version>
</dependency>

Python

# Python
pip install alibabacloud_realtranslationagent20260622==1.0.0

Node.js

# Node.js
npm install @alicloud/realtranslationagent20260622@1.0.0

Go

# Go
go get github.com/alibabacloud-go/realtranslationagent-20260622/client@v1.0.0

C#

# C#
dotnet add package AlibabaCloud.SDK.RealTranslationAgent20260622 --version 1.0.0

PHP

# PHP
composer require alibabacloud/realtranslationagent-20260622 1.0.0

C++

# C++
vcpkg install alibabacloud-sdk-realtranslationagent-20260622

Swift

// Swift - 在 Package.swift 中添加依赖
.package(url: "https://github.com/alibabacloud-sdk-swift/realtranslationagent-20260622", from: "1.0.0")

初始化客户端

Java

import com.aliyun.realtranslationagent20260622.Client;
import com.aliyun.teaopenapi.models.Config;

Config config = new Config()
        .setAccessKeyId("your-access-key-id")
        .setAccessKeySecret("your-access-key-secret")
        .setEndpoint("realtranslationagent.aliyuncs.com");
Client client = new Client(config);

Python

from alibabacloud_realtranslationagent20260622.client import Client
from alibabacloud_tea_openapi.models import Config

config = Config(
    access_key_id="your-access-key-id",
    access_key_secret="your-access-key-secret",
    endpoint="realtranslationagent.aliyuncs.com"
)
client = Client(config)

Node.js

import Client from '@alicloud/realtranslationagent20260622';
import { Config } from '@alicloud/openapi-client';

const config = new Config({
    accessKeyId: 'your-access-key-id',
    accessKeySecret: 'your-access-key-secret',
    endpoint: 'realtranslationagent.aliyuncs.com',
});

const client = new Client(config);

Go

import (
    client "github.com/alibabacloud-go/realtranslationagent-20260622/client"
    openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
    "github.com/alibabacloud-go/tea/tea"
)

config := &openapi.Config{
    AccessKeyId:     tea.String("your-access-key-id"),
    AccessKeySecret: tea.String("your-access-key-secret"),
    Endpoint:        tea.String("realtranslationagent.aliyuncs.com"),
}

c, err := client.NewClient(config)

C#

using AlibabaCloud.SDK.RealTranslationAgent20260622;
using AlibabaCloud.OpenApiClient.Models;

var config = new Config
{
    AccessKeyId = "your-access-key-id",
    AccessKeySecret = "your-access-key-secret",
    Endpoint = "realtranslationagent.aliyuncs.com"
};

var client = new Client(config);

PHP

use AlibabaCloud\SDK\RealTranslationAgent\V20260622\RealTranslationAgent;
use Darabonba\OpenApi\Models\Config;

$config = new Config([
    'accessKeyId' => 'your-access-key-id',
    'accessKeySecret' => 'your-access-key-secret',
    'endpoint' => 'realtranslationagent.aliyuncs.com',
]);

$client = new RealTranslationAgent($config);

调用流程总览

核心流程详解

流程一：上传 → 提交 → 轮询 → 下载

这是最常见的翻译流程，适用于新文档翻译场景。

上传文件并预估

调用 UploadTranslationFile 上传文档，获取文档解析结果和预估信息。

该接口返回：
- TaskId — 后续操作的唯一标识
- WordCount / PageCount — 字数和页数统计
- EstimatedCostCredits — 预估 Credits 消耗
- DetectedLang — 自动检测的源语种
- Fonts — 可选的目标字体列表
- SensitiveDetected — 是否检测到敏感内容
说明
此步骤不产生任何费用，您可以根据预估结果决定是否继续提交翻译。
提交翻译任务

确认预估结果后，调用 SubmitTranslationTask 正式提交翻译任务。

需要传入：
- TaskId — 上一步获取的任务 ID
- Config — 翻译配置（源/目标语言、字体等）
- CustomTerms（可选）— 自定义术语对
提交成功后任务进入 PENDING 状态，随后自动开始处理。
轮询任务进度

调用 GetTranslationTask 轮询任务状态和进度。

建议轮询间隔为 3~5 秒，直到状态变为终态：
- COMPLETED — 翻译完成，可下载译文
- FAILED — 翻译失败，查看 ErrorMessage
- CANCELLED — 已取消
下载译文

任务完成后，调用 GetTranslatedFileUrl 获取译文的临时下载链接。

如需下载原文，调用 GetOriginalFileUrl。

说明
下载链接默认有效期为 1 小时，过期后需重新获取。

流程二：取消翻译任务

在任务处理过程中，可调用 CancelTranslationTask 取消任务。取消成功后冻结的 Credits 将全额返还。

流程三：查询历史任务

调用 ListTranslationTasks 分页查询历史任务列表，支持按状态、语种、文件名和时间范围筛选。

流程四：重新翻译

对已有任务重新发起翻译时，调用 SubmitTranslationTask 并传入 BaseTaskId（历史任务 ID）替代 TaskId，无需重新上传文件。

任务状态说明

状态	说明	可执行操作
`ANALYZED`	文件已上传并完成分析	提交翻译
`PENDING`	任务已提交，等待处理	取消任务
`PROCESSING`	翻译处理中	取消任务、查询进度
`COMPLETED`	翻译完成	下载译文/原文
`FAILED`	翻译失败	查看错误信息
`CANCELLED`	已取消	—

完整代码示例

import com.aliyun.realtranslationagent20260622.Client;
import com.aliyun.realtranslationagent20260622.models.*;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

import java.io.File;
import java.io.FileInputStream;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;

public class TranslationExample {

    public static void main(String[] args) throws Exception {
        // 1. 初始化客户端
        Config config = new Config()
                .setAccessKeyId("your-access-key-id")
                .setAccessKeySecret("your-access-key-secret")
                .setEndpoint("realtranslationagent.aliyuncs.com");
        Client client = new Client(config);

        // 2. 上传文件并预估
        File file = new File("/path/to/document.docx");
        InputStream fileStream = new FileInputStream(file);

        UploadTranslationFileAdvanceRequest uploadRequest =
                new UploadTranslationFileAdvanceRequest()
                        .setFileObject(fileStream)
                        .setFileName(file.getName());
        // 成员账号需设置 API Key
        // uploadRequest.setAPIKey("sk-your-api-key");

        RuntimeOptions runtimeOptions = new RuntimeOptions();
        UploadTranslationFileResponse uploadResponse =
                client.uploadTranslationFileAdvance(uploadRequest, runtimeOptions);

        String taskId = uploadResponse.getBody().getData().getTaskId();
        System.out.println("TaskId: " + taskId);
        System.out.println("预估 Credits: " + uploadResponse.getBody().getData().getEstimatedCostCredits());

        // 3. 提交翻译任务
        SubmitTranslationTaskRequest.SubmitTranslationTaskRequestConfig translateConfig =
                new SubmitTranslationTaskRequest.SubmitTranslationTaskRequestConfig()
                        .setSourceLanguage(uploadResponse.getBody().getData().getDetectedLang())
                        .setTargetLanguage("en")
                        .setFont("Calibri");

        // 自定义术语（可选）
        List<SubmitTranslationTaskRequest.SubmitTranslationTaskRequestCustomTerms> customTerms = new ArrayList<>();
        customTerms.add(new SubmitTranslationTaskRequest.SubmitTranslationTaskRequestCustomTerms()
                .setSourceTerm("人工智能")
                .setTargetTerm("Artificial Intelligence"));

        SubmitTranslationTaskRequest submitRequest = new SubmitTranslationTaskRequest()
                .setTaskId(taskId)
                .setConfig(translateConfig)
                .setCustomTerms(customTerms);

        SubmitTranslationTaskResponse submitResponse = client.submitTranslationTask(submitRequest);
        System.out.println("任务状态: " + submitResponse.getBody().getData().getStatus());

        // 4. 轮询任务进度
        String status;
        do {
            Thread.sleep(5000);
            GetTranslationTaskRequest getRequest = new GetTranslationTaskRequest()
                    .setTaskId(taskId);
            GetTranslationTaskResponse getResponse = client.getTranslationTask(getRequest);
            status = getResponse.getBody().getData().getStatus();
            System.out.println("进度: " + getResponse.getBody().getData().getProgress() + "%, 状态: " + status);
        } while ("PENDING".equals(status) || "PROCESSING".equals(status));

        // 5. 下载译文
        if ("COMPLETED".equals(status)) {
            GetTranslatedFileUrlRequest downloadRequest = new GetTranslatedFileUrlRequest()
                    .setTaskId(taskId);
            GetTranslatedFileUrlResponse downloadResponse = client.getTranslatedFileUrl(downloadRequest);
            System.out.println("译文下载链接: " + downloadResponse.getBody().getData().getDownloadUrl());
        }
    }
}