Skip to content

Commit 0fe7c53

Browse files
daniel-jones-devJanEbbing
daniel-jones-dev
authored and
JanEbbing
committed
feat: add /write/rephrase endpoint
1 parent 9f93a54 commit 0fe7c53

File tree

4 files changed

+413
-0
lines changed

4 files changed

+413
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,11 @@ number is used only for corrections to the OpenAPI specification, for example:
1010
typos, schema fixes, or adding examples.
1111

1212

13+
### [Unreleased] - 2025-01-16
14+
### Added
15+
* Add new endpoint `/write/rephrase` which enables text corrections and adjustments in selected languages
16+
17+
1318
### [2.17.0] - 2024-11-15
1419
### Added
1520
* `/translate`: add `model_type` request parameter to request the model type
@@ -164,6 +169,7 @@ typos, schema fixes, or adding examples.
164169
Initial release of the OpenAPI specification.
165170

166171

172+
[Unreleased]: https://github.com/DeepLcom/openapi/compare/v2.17.0...HEAD
167173
[2.17.0]: https://github.com/DeepLcom/openapi/compare/v2.16.0...v2.17.0
168174
[2.16.0]: https://github.com/DeepLcom/openapi/compare/v2.15.0...v2.16.0
169175
[2.15.0]: https://github.com/DeepLcom/openapi/compare/v2.14.1...v2.15.0

‎openapi.json‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,10 @@
3333
"name": "TranslateDocuments",
3434
"description": "The document translation API allows you to translate whole documents and supports the following file types and extensions:\n * `docx` - Microsoft Word Document\n * `pptx` - Microsoft PowerPoint Document\n * `xlsx` - Microsoft Excel Document\n * `pdf` - Portable Document Format\n * `htm / html` - HTML Document\n * `txt` - Plain Text Document\n * `xlf / xliff` - XLIFF Document, version 2.1\n * `srt` - SRT Document\n\nPlease note that with every submitted document of type .pptx, .docx, .xlsx, or .pdf,\nyou are billed a minimum of 50,000 characters with the DeepL API plan,\nno matter how many characters are included in the document.\n\n\nTranslating a document usually involves three types of HTTP requests:\n - [upload](https://www.deepl.com/docs-api/documents/translate-document) the document to be translated,\n - periodically [check the status](https://www.deepl.com/docs-api/documents/get-document-status) of the document translation,\n - once the status call reports `done`, [download](https://www.deepl.com/docs-api/documents/download-document) the translated document.\n\n\nTo learn more about context in DeepL API translations, we recommend [this article](https://www.deepl.com/docs-api/general/working-with-context)."
3535
},
36+
{
37+
"name": "RephraseText",
38+
"description": "The `rephrase` endpoint is used to make corrections and adjustments to texts based on style or tone.\nFor more details, visit [this documentation page](https://developers.deepl.com/docs/api-reference/improve-text)."
39+
},
3640
{
3741
"name": "ManageGlossaries",
3842
"description": "The *glossary* functions allow you to create, inspect, and delete glossaries.\nGlossaries created with the glossary function can be used in translate requests by specifying the\n`glossary_id` parameter.\nIf you encounter issues, please let us know at support@DeepL.com.\n\nThe DeepL API supports glossaries in any combination of two languages from the following list, enabling a total of\n120 possible glossary language pairs:\n\n- DA (Danish)\n- DE (German)\n- EN (English)\n- ES (Spanish)\n- FR (French)\n- IT (Italian)\n- JA (Japanese)\n- KO (Korean)\n- NB (Norwegian (bokm\u00e5l))\n- NL (Dutch)\n- PL (Polish)\n- PT (Portuguese)\n- RO (Romanian)\n- RU (Russian)\n- SV (Swedish)\n- ZH (Chinese)\n\nThe maximum size limit for a glossary is 10 MiB = 10485760 bytes and each source/target text,\nas well as the name of the glossary, is limited to 1024 UTF-8 bytes.\nA total of 1000 glossaries are allowed per account.\n\nWhen creating a glossary with target language `EN`, `PT`, or `ZH`, it's not necessary to specify a variant\n(e.g. `EN-US`, `EN-GB`, `PT-PT`, `PT-BR`, or `ZH-HANS`).\nGlossaries with target language `EN` can be used in translations with either English variant.\nSimilarly `PT`, and `ZH` glossaries can be used in translations with their corresponding variants.\n\n\nGlossaries created via the DeepL API are distinct from glossaries created via the DeepL website and DeepL apps.\nThis means API glossaries cannot be used on the website and vice versa.\n\n\n\nNote that glossaries are immutable: once created, the glossary entries for a given glossary ID cannot be modified.\n\nAs a workaround for effectively editable glossaries, we suggest to identify glossaries by name instead of ID in your application\nand then use the following procedure for modifications:\n- [download](https://www.deepl.com/docs-api/glossaries/get-glossary-entries) and store the current glossary's entries,\n- locally modify the glossary entries,\n- [delete](https://www.deepl.com/docs-api/glossaries/delete-glossary) the existing glossary,\n- [create a new glossary](https://www.deepl.com/docs-api/glossaries/create-glossary) with the same name."
@@ -1208,6 +1212,112 @@
12081212
]
12091213
}
12101214
},
1215+
"/write/rephrase": {
1216+
"post": {
1217+
"tags": [
1218+
"RephraseText"
1219+
],
1220+
"summary": "Request text improvement",
1221+
"operationId": "rephraseText",
1222+
"requestBody": {
1223+
"required": true,
1224+
"content": {
1225+
"application/json": {
1226+
"schema": {
1227+
"type": "object",
1228+
"required": [
1229+
"text"
1230+
],
1231+
"properties": {
1232+
"text": {
1233+
"description": "Text to be improved. Only UTF-8-encoded plain text is supported. Improvements are returned in the same order as they are requested.",
1234+
"type": "array",
1235+
"items": {
1236+
"type": "string",
1237+
"example": "this is a example sentence to imprve"
1238+
}
1239+
},
1240+
"target_lang": {
1241+
"$ref": "#/components/schemas/TargetLanguageWrite"
1242+
},
1243+
"writing_style": {
1244+
"$ref": "#/components/schemas/WritingStyle"
1245+
},
1246+
"tone": {
1247+
"$ref": "#/components/schemas/WritingTone"
1248+
}
1249+
}
1250+
}
1251+
},
1252+
"application/x-www-form-urlencoded": {
1253+
"schema": {
1254+
"type": "object",
1255+
"required": [
1256+
"text"
1257+
],
1258+
"properties": {
1259+
"text": {
1260+
"description": "Text to be improved. Only UTF-8-encoded plain text is supported. Improvements are returned in the same order as they are requested.",
1261+
"type": "array",
1262+
"items": {
1263+
"type": "string",
1264+
"example": "this is a example sentence to imprve"
1265+
}
1266+
},
1267+
"target_lang": {
1268+
"$ref": "#/components/schemas/TargetLanguageWrite"
1269+
},
1270+
"writing_style": {
1271+
"$ref": "#/components/schemas/WritingStyle"
1272+
},
1273+
"tone": {
1274+
"$ref": "#/components/schemas/WritingTone"
1275+
}
1276+
}
1277+
}
1278+
}
1279+
}
1280+
},
1281+
"responses": {
1282+
"200": {
1283+
"description": "Successful text improvement.",
1284+
"content": {
1285+
"application/json": {
1286+
"schema": {
1287+
"type": "object",
1288+
"properties": {
1289+
"improvements": {
1290+
"type": "array",
1291+
"minItems": 1,
1292+
"items": {
1293+
"type": "object",
1294+
"properties": {
1295+
"detected_source_language": {
1296+
"description": "The language detected in the source text.",
1297+
"type": "string",
1298+
"example": "en"
1299+
},
1300+
"text": {
1301+
"description": "The improved text.",
1302+
"type": "string",
1303+
"example": "This is a sample sentence to improve."
1304+
}
1305+
}
1306+
}
1307+
}
1308+
}
1309+
}
1310+
}
1311+
}
1312+
}
1313+
},
1314+
"security": [
1315+
{
1316+
"auth_header": []
1317+
}
1318+
]
1319+
}
1320+
},
12111321
"/usage": {
12121322
"get": {
12131323
"tags": [
@@ -2123,6 +2233,52 @@
21232233
"ZH-HANT"
21242234
],
21252235
"example": "DE"
2236+
},
2237+
"TargetLanguageWrite": {
2238+
"type": "string",
2239+
"description": "The language for the text improvement. Options currently available:\n * `de` - German\n * `en` - English (unspecified variant, defaults to `en-US`)\n * `en-GB` - English (British)\n * `en-US` - English (American)\n * `es` - Spanish\n * `fr` - French\n * `it` - Italian\n * `pt` - Portuguese (unspecified variant, defaults to `pt-PT`)\n * `pt-BR` - Portuguese (Brazilian)\n * `pt-PT` - Portuguese (all Portuguese variants excluding Brazilian Portuguese)",
2240+
"enum": [
2241+
"de",
2242+
"en",
2243+
"en-GB",
2244+
"en-US",
2245+
"fr",
2246+
"it",
2247+
"pt",
2248+
"pt-BR",
2249+
"pt-PT"
2250+
],
2251+
"example": "de"
2252+
},
2253+
"WritingStyle": {
2254+
"type": "string",
2255+
"description": "Specify a style to rephrase your text in a way that fits your audience and goals.\nThe `prefer_` prefix allows falling back to the default style if the language does not yet support styles.",
2256+
"enum": [
2257+
"academic",
2258+
"business",
2259+
"casual",
2260+
"default",
2261+
"simple",
2262+
"prefer_academic",
2263+
"prefer_business",
2264+
"prefer_casual",
2265+
"prefer_simple"
2266+
]
2267+
},
2268+
"WritingTone": {
2269+
"type": "string",
2270+
"description": "Specify the desired tone for your text.\nThe `prefer_` prefix allows falling back to the default tone if the language does not yet support tones.",
2271+
"enum": [
2272+
"confident",
2273+
"default",
2274+
"diplomatic",
2275+
"enthusiastic",
2276+
"friendly",
2277+
"prefer_confident",
2278+
"prefer_diplomatic",
2279+
"prefer_enthusiastic",
2280+
"prefer_friendly"
2281+
]
21262282
}
21272283
}
21282284
}

‎openapi.yaml‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,11 @@ tags:
4646
4747
4848
To learn more about context in DeepL API translations, we recommend [this article](https://www.deepl.com/docs-api/general/working-with-context).
49+
- name: RephraseText
50+
description: |-
51+
The `rephrase` endpoint is used to make corrections and adjustments to texts based on style or tone.
52+
53+
For more details, visit [this documentation page](https://developers.deepl.com/docs/api-reference/improve-text)
4954
- name: ManageGlossaries
5055
description: |-
5156
The *glossary* functions allow you to create, inspect, and delete glossaries.
@@ -943,6 +948,77 @@ paths:
943948
$ref: '#/components/responses/TooManyRequests'
944949
security:
945950
- auth_header: []
951+
/write/rephrase:
952+
post:
953+
tags:
954+
- RephraseText
955+
summary: Request text improvement
956+
operationId: rephraseText
957+
requestBody:
958+
required: true
959+
content:
960+
application/json:
961+
schema:
962+
type: object
963+
required:
964+
- text
965+
properties:
966+
text:
967+
description: Text to be improved. Only UTF-8-encoded plain text is supported. Improvements are
968+
returned in the same order as they are requested.
969+
type: array
970+
items:
971+
type: string
972+
example: this is a example sentence to imprve
973+
target_lang:
974+
$ref: '#/components/schemas/TargetLanguageWrite'
975+
writing_style:
976+
$ref: '#/components/schemas/WritingStyle'
977+
tone:
978+
$ref: '#/components/schemas/WritingTone'
979+
application/x-www-form-urlencoded:
980+
schema:
981+
type: object
982+
required:
983+
- text
984+
properties:
985+
text:
986+
description: Text to be improved. Only UTF-8-encoded plain text is supported. Improvements are
987+
returned in the same order as they are requested.
988+
type: array
989+
items:
990+
type: string
991+
example: this is a example sentence to imprve
992+
target_lang:
993+
$ref: '#/components/schemas/TargetLanguageWrite'
994+
writing_style:
995+
$ref: '#/components/schemas/WritingStyle'
996+
tone:
997+
$ref: '#/components/schemas/WritingTone'
998+
responses:
999+
200:
1000+
description: Successful text improvement.
1001+
content:
1002+
application/json:
1003+
schema:
1004+
type: object
1005+
properties:
1006+
improvements:
1007+
type: array
1008+
minItems: 1
1009+
items:
1010+
type: object
1011+
properties:
1012+
detected_source_language:
1013+
description: The language detected in the source text.
1014+
type: string
1015+
example: en
1016+
text:
1017+
description: The improved text.
1018+
type: string
1019+
example: This is a sample sentence to improve.
1020+
security:
1021+
- auth_header: []
9461022
/usage:
9471023
get:
9481024
tags:
@@ -2036,3 +2112,58 @@ components:
20362112
- ZH-HANS
20372113
- ZH-HANT
20382114
example: DE
2115+
TargetLanguageWrite:
2116+
type: string
2117+
description: |-
2118+
The language for the text improvement. Options currently available:
2119+
* `de` - German
2120+
* `en` - English (unspecified variant, defaults to `en-US`)
2121+
* `en-GB` - English (British)
2122+
* `en-US` - English (American)
2123+
* `es` - Spanish
2124+
* `fr` - French
2125+
* `it` - Italian
2126+
* `pt` - Portuguese (unspecified variant, defaults to `pt-PT`)
2127+
* `pt-BR` - Portuguese (Brazilian)
2128+
* `pt-PT` - Portuguese (all Portuguese variants excluding Brazilian Portuguese)
2129+
enum:
2130+
- de
2131+
- en
2132+
- en-GB
2133+
- en-US
2134+
- fr
2135+
- it
2136+
- pt
2137+
- pt-BR
2138+
- pt-PT
2139+
example: de
2140+
WritingStyle:
2141+
type: string
2142+
description: |-
2143+
Specify a style to rephrase your text in a way that fits your audience and goals.
2144+
The `prefer_` prefix allows falling back to the default style if the language does not yet support styles.
2145+
enum:
2146+
- academic
2147+
- business
2148+
- casual
2149+
- default
2150+
- simple
2151+
- prefer_academic
2152+
- prefer_business
2153+
- prefer_casual
2154+
- prefer_simple
2155+
WritingTone:
2156+
type: string
2157+
description: |-
2158+
Specify the desired tone for your text.
2159+
The `prefer_` prefix allows falling back to the default tone if the language does not yet support tones.
2160+
enum:
2161+
- confident
2162+
- default
2163+
- diplomatic
2164+
- enthusiastic
2165+
- friendly
2166+
- prefer_confident
2167+
- prefer_diplomatic
2168+
- prefer_enthusiastic
2169+
- prefer_friendly

0 commit comments

Comments
 (0)