Marco Translator API Reference（Batch）

GET/POST /ai/text/marco/translator

Batch Invocation Guide

Strengths

• High Efficiency: Batch invocation allows processing large volumes of text at once, significantly improving translation efficiency and saving both time and manpower.

• Multilingual Support: Marco supports translation between 42 languages, meeting global multilingual needs and reducing reliance on multiple translation tools.

• High Accuracy: Delivers excellent performance in e-commerce terminology and daily conversation translations, handling complex linguistic scenarios to ensure translation quality.

• Cost-effective: Batch invocation reduces repetitive operations compared to translating texts one by one, making it suitable for large-scale language processing in enterprises.

• Strong Scalability: Offers flexible API invocation methods and can be seamlessly integrated with existing enterprise systems or platforms, adapting to various business scenarios.

• Automation: Batch invocation is often combined with automated workflows, minimizing manual intervention and enhancing the overall intelligence of business processes.

Limitations

• Resource Consumption: Batch invocation may require significant computational resources, especially when processing large-scale texts. Ensure server or environment stability during usage.

• Processing Time: For extremely large text volumes or language combinations, batch invocation may increase processing time and affect real-time performance.

• Terminology Adjustment: In certain specialized fields, translation results may require manual adjustments to fit specific industry terminology or brand style.

• API Call Restrictions: Batch invocation may be subject to limitations such as call frequency, text length, or supported language combinations.

• Error Accumulation Risk: If input texts contain errors or ambiguous expressions, batch invocation may lead to the accumulation of errors in translation results, impacting overall quality.

Request Parameters

Parameter	Type	Required	Description
text	List	Yes	Translation Text; The total character length should not exceed 50,000, and the list length should not exceed 50. Sample value:"[\"Pen for iPad, 13 mins Fast Charging Stylus with Palm Rejection, Tilt Sensitivity, Compatible with 2018-2022 iPad Air 3/4/5, iPad Mini 5/6, iPad 6/7/8/9/10, iPad Pro 11, iPad Pro 12.9 (Black)\"]"
sourceLanguage	List	No	Source language code, which can be viewed in the following translation supported language list. If this parameter is not provided, the language will be automatically detected. Sample value:["en","es"]
targetLanguage	String	Yes	Target language code, which can be viewed in the following language detection supported language list. Sample value:"ko"
formatType	String	No	The format type of source text； Currently text/html are avaliable, default: text. Sample value:"text"
glossary	List	No	Intervention Glossary ID Array；Multiple intervention glossaries can be passed. If the provided intervention glossary IDs are empty, the translation results will not be modified. Self-service upload of intervention glossary IDs is not currently supported. Sample value:["translation_glossary1","translation_glossary2"]

Sample Request

import java.util.ArrayList;
import java.util.List;

/*The domain url of the API.  
*for api purchased on global site. set api_domain to "https://api.aidc-ai.com"  
*for APIs purchased on the Chinese site, please use the domain"https://cn-api.aidc-ai.com"域名 (for api purchased on chinese site) set api_domain to "https://cn-api.aidc-ai.com"*/

IopClient client = new IopClientImpl("domain url", "your key", "your secret");
IopRequest request = new IopRequest();

/Please add a trial flag to your request to prevent the NoResource error code
request.addHeaderParameter("x-iop-trial", "true");

// Set API name
request.setApiName("/ai/text/marco/translator");

// Set the text array for batch translation.
List<String> texts = new ArrayList<>();
texts.add("Pen for iPad, 13 mins Fast Charging Stylus with Palm Rejection, Tilt Sensitivity, Compatible with 2018-2022 iPad Air 3/4/5, iPad Mini 5/6, iPad 6/7/8/9/10, iPad Pro 11, iPad Pro 12.9 (Black)");
texts.add("Another example text to translate.");
request.addApiParameter("text", texts);

// Set the source language array (optional, auto-detection available).
List<String> sourceLanguages = new ArrayList<>();
sourceLanguages.add("en");
sourceLanguages.add("es");
request.addApiParameter("sourceLanguage", sourceLanguages);

// Set the target language
request.addApiParameter("targetLanguage", "ko");

// Set the format type (optional, default is 'text')
request.addApiParameter("formatType", "text");

// Set the intervention lexicon ID array (optional)
List<String> glossaries = new ArrayList<>();
glossaries.add("translation_glossary1");
glossaries.add("translation_glossary2");
request.addApiParameter("glossary", glossaries);

// Execute the request
IopResponse response = client.execute(request);

// Output the response result
System.out.println(response.getBody());

// Delayed processing
Thread.sleep(10);

Batch Invocation Response Time Guidelines:

• Single Request Response Time Limit

Although the maximum response time for a single invocation is 30 seconds, each request within a batch call must still be controlled within 30 seconds. If a batch call contains multiple translation tasks, it is recommended to set an individual response time limit of 30 seconds for each task to prevent overall workflow delays caused by individual task timeouts.

• Overall Response Time for Batch Invocation

The total response time for batch calls will increase according to the number and complexity of tasks. However, it is advisable not to set an excessively long overall invocation time to ensure system real-time performance and stability. If the task volume is large, it is recommended to split batch requests into smaller sub-batches, with the response time for each sub-batch still capped at 30 seconds.

• Optimization Recommendations

Task Segmentation: Divide large translation tasks into multiple smaller batches, each containing an appropriate amount of text, to ensure that the processing time for each batch does not exceed 30 seconds. Resource Allocation: Batch invocation usually requires more computational resources. Allocate server resources according to task volume to avoid prolonged response times due to resource shortages. Timeout Settings: Set reasonable timeout values (e.g., 30 seconds) for each request when calling the API, to prevent individual request delays from affecting the overall workflow. Error Handling: For timed-out or failed tasks, implement retry mechanisms or logging features for follow-up processing.

• Notes

If batch calls include multiple language combinations, especially complex pairs (such as low-resource languages or long text translations), response times may approach or reach the 30-second upper limit. Avoid submitting too many tasks in a single batch to prevent decreased system performance or poor user experience due to excessive response times.

Parameter Response

Parameter	Type	Description
resCode	Number	Response code； 200 indicates a successful call, other response codes can be referred to in the error code information.
data	Object	The structure of the returned translation result.
data.translations	List	Details of the returned translation result
data.translations.characters	Number	The number of characters translated.
data.translations.translatedText	String	Result data that translated.
data.translations.detectedLanguage	String	Language Detection Results.
requestId	String	Request ID: Used to uniquely identify a single request call.
success	Boolean	Whether successful；true is successful，false is unsuccessful.
resMessage	String	Error message，like "content has sensitive data, please try other input".

Sample Response

{
  "data": {
    "translations": [
      {
        "translatedText": "iPad용 펜, 손바닥 거부 기능이 있는 13분 고속 충전 스타일러스, 기울기 감도, 2018-2022 iPad Air 3/4/5, iPad Mini 5/6, iPad 6/7/8/9/10, iPad Pro 11, iPad Pro 12.9와 호환 가능(검은색)",
        "characters": 142,
        "detectedLanguage": "en"
      },
      {
        "translatedText": "もう一つの翻訳テキストの例。",
        "characters": 20,
        "detectedLanguage": "es"
      }
    ],
    "class": "com.aidc.service.api.client.translate.dto.CommonTranslationResponse"
  },
  "requestId": "2101364017192321239846748e03d8",
  "success": true,
  "resCode": 200,
  "resMessage": "success",
  "code": "0",
  "request_id": "2101236717192321239867892",
  "_trace_id_": "2101364017192321239846748e03d8"
}

Error Code

code	Error code	Description
500	system error	System error
501	Rate limit exceed	The current interface has reached the current limit. Please contact us via Discord or email us ([email protected]) to increase the current limit value.
700	Invalid input	The format of the input parameters does not meet the requirements, and resMessage will return detailed fields that do not meet the requirements.
801	Model failed	Internal call exception, please contact us via Discord or email us ([email protected]) for troubleshooting.
900	Batch task failed	Batch task execution failed. Please check whether the input file format or content meets the requirements.
901	Batch file format invalid	The input file format in batch invocation does not meet the requirements. Please ensure the file format is correct.
902	Batch file size exceeded	The input file size in batch invocation exceeds the limit. Please reduce the file size and try again.
903	Batch request count exceeded	The number of requests in batch invocation exceeds the limit. Please reduce the number of tasks in the batch and try again.
1000	Content has sensitive data, please try other input	The request parameters contain sensitive information and cannot be processed at this time. Please try a different input.
1001	Content control failed, please retry	The risk control service failed. Please try again. If the error persists, please contact us via Discord or email us ([email protected]) .
1002	Content risk filter failed, please contact us	Content risk filter failed, please contact us via Discord or email us ([email protected]) .
1007	Text language is not supported	some text languages in the batch invocation are not supported. Please verify that the input languages are correct.
1100	The input text length is too long	Some texts in the batch invocation exceed the maximum length limit (4096 tokens). Please check and re-enter texts that comply with the length restriction.