diff --git a/api-reference/improve-text.mdx b/api-reference/improve-text.mdx index 159628fe..544280aa 100644 --- a/api-reference/improve-text.mdx +++ b/api-reference/improve-text.mdx @@ -14,10 +14,15 @@ sidebarTitle: "Overview" ### DeepL API for Write overview -DeepL API for Write is accessible through an HTTP interface and currently consists of a single endpoint for text improvement, `/write/rephrase`, which is described below. The endpoint: +DeepL API for Write is accessible through an HTTP interface and consists of two endpoints: -* Accepts both form-encoded (`Content-Type: application/x-www-form-urlencoded`) and JSON-encoded (`Content-Type: application/json`) request bodies -* Returns JSON-encoded responses +* [`/write/rephrase`](/api-reference/improve-text/request-text-improvement) — broad text improvement. Fixes spelling and grammar and may also rewrite sentences for clarity, style, or tone. +* [`/write/correct`](/api-reference/improve-text/correct-text) — corrections-only mode. Fixes spelling and grammar errors with minimal changes to wording. Use this when you want the model to leave the author's voice intact. + +Both endpoints: + +* Accept both form-encoded (`Content-Type: application/x-www-form-urlencoded`) and JSON-encoded (`Content-Type: application/json`) request bodies +* Return JSON-encoded responses The client libraries support all features of the text improvement endpoint. The text improvement feature is currently only available to DeepL API Pro customers and is not yet available in DeepL API Free. @@ -179,6 +184,6 @@ We've added a new column to the [API key-level usage report](/docs/getting-start #### Is "Corrections Only" mode available in the API? -No. "Corrections Only" is a mode that fixes spelling and grammatical errors only without broader rephrasing. It is currently only available in the DeepL Translator UI. +Yes. Send your request to [`/write/correct`](/api-reference/improve-text/correct-text). This endpoint fixes spelling and grammar errors with minimal changes to wording, matching the "Corrections Only" mode in the DeepL Translator UI. -If you make an API request to `/write/rephrase` and omit both `writing_style` and `tone`, the API uses its default improvement mode. This corrects grammar and spelling but may also make broader changes than the "Corrections Only" mode in the UI. +If you instead send a request to `/write/rephrase` and omit both `writing_style` and `tone`, the API uses its default improvement mode. This corrects grammar and spelling but may also make broader changes than `/write/correct`. diff --git a/api-reference/improve-text/correct-text.mdx b/api-reference/improve-text/correct-text.mdx new file mode 100644 index 00000000..ba0a3dd2 --- /dev/null +++ b/api-reference/improve-text/correct-text.mdx @@ -0,0 +1,7 @@ +--- +openapi: post /v2/write/correct +title: "Correct text" +description: "Fixes spelling and grammar errors with minimal changes to wording." +--- + +The `/v2/write/correct` endpoint fixes spelling and grammar errors in one or more texts with minimal changes to wording, matching the "Corrections Only" mode in the DeepL Translator UI. It does not accept `writing_style` or `tone` and does not rephrase sentences for clarity. The broader [`/v2/write/rephrase`](/api-reference/improve-text/request-text-improvement) endpoint supports those parameters. diff --git a/api-reference/improve-text/request-text-improvement.mdx b/api-reference/improve-text/request-text-improvement.mdx index bd123ba1..9d7dcc1d 100644 --- a/api-reference/improve-text/request-text-improvement.mdx +++ b/api-reference/improve-text/request-text-improvement.mdx @@ -1,3 +1,7 @@ --- openapi: post /v2/write/rephrase ---- \ No newline at end of file +title: "Improve text" +description: "Improves text by correcting spelling and grammar and rewriting for a target writing style or tone." +--- + +The `/v2/write/rephrase` endpoint improves one or more texts by correcting spelling and grammar and rephrasing sentences for clarity. With the optional `writing_style` or `tone` parameters, the rewrite targets a specific style or tone. Its corrections-only counterpart, [`/v2/write/correct`](/api-reference/improve-text/correct-text), is limited to fixing mistakes with minimal changes to wording. diff --git a/api-reference/openapi.json b/api-reference/openapi.json index fa88d772..4638b317 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -41,6 +41,10 @@ "name": "RephraseText", "description": "The `rephrase` endpoint is used to make corrections and adjustments to texts based on style or tone." }, + { + "name": "CorrectText", + "description": "The `correct` endpoint fixes spelling and grammar errors without broader rephrasing. Use it when you want\na minimal-change correction pass rather than the broader rewriting performed by `rephrase`." + }, { "name": "ManageMultilingualGlossaries", "description": "The *glossary* functions allow you to create, inspect, edit and delete glossaries.\nGlossaries created with the glossary function can be used in translate requests by specifying the\n`glossary_id` parameter. A glossary contains (several) dictionaries.\nA dictionary is a mapping of source phrases to target phrases for a single language pair.\nIf you encounter issues, please let us know at support@DeepL.com.\n\nCurrently you can create glossaries with any of the languages DeepL supports (with the exception of Thai).\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 dictionary 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`).\nDictionaries with target language `EN` can be used in translations with either English variant.\nSimilarly `PT`, and `ZH` dictionaries can be used in translations with their corresponding variants.\n(When you provide the ID of a glossary to a translation, the appropriate dictionary is automatically applied. Currently glossaries can not yet be used with source language detection.)\n\nGlossaries created via the DeepL API are now unified with glossaries created via the DeepL website and DeepL apps.\nPlease only use the v3 glossary API in conjunction with multilingual or edited glossaries from the website." @@ -2409,7 +2413,7 @@ "tags": [ "RephraseText" ], - "summary": "Request text improvement", + "summary": "Improve text", "operationId": "rephraseText", "requestBody": { "required": true, @@ -2494,6 +2498,11 @@ "type": "string", "example": "en" }, + "target_language": { + "description": "The target language specified by the request.", + "type": "string", + "example": "en-US" + }, "text": { "description": "The improved text.", "type": "string", @@ -2515,6 +2524,135 @@ ] } }, + "/v2/write/correct": { + "post": { + "tags": [ + "CorrectText" + ], + "summary": "Correct text", + "description": "Fix spelling and grammar errors in one or more texts. Unlike `/v2/write/rephrase`, this endpoint applies\na minimal-change correction pass and does not rewrite the text for style or tone.", + "operationId": "correctText", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "text" + ], + "properties": { + "text": { + "description": "Text to be corrected. Only UTF-8-encoded plain text is supported. Corrections are returned in the same order as they are requested.", + "type": "array", + "items": { + "type": "string", + "example": "this is a example sentence to imprve" + } + }, + "target_lang": { + "$ref": "#/components/schemas/TargetLanguageWrite" + } + } + } + }, + "application/x-www-form-urlencoded": { + "schema": { + "type": "object", + "required": [ + "text" + ], + "properties": { + "text": { + "description": "Text to be corrected. Only UTF-8-encoded plain text is supported. Corrections are returned in the same order as they are requested.", + "type": "array", + "items": { + "type": "string", + "example": "this is a example sentence to imprve" + } + }, + "target_lang": { + "$ref": "#/components/schemas/TargetLanguageWrite" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful text correction.", + "headers": { + "X-Trace-ID": { + "$ref": "#/components/headers/X-Trace-ID" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "improvements": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "properties": { + "detected_source_language": { + "description": "The language detected in the source text.", + "type": "string", + "example": "en" + }, + "target_language": { + "description": "The target language specified by the request.", + "type": "string", + "example": "en-US" + }, + "text": { + "description": "The corrected text.", + "type": "string", + "example": "This is a sample sentence to improve." + } + } + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "413": { + "$ref": "#/components/responses/PayloadTooLarge" + }, + "415": { + "description": "Unsupported Content-Type. Use `application/json` or `application/x-www-form-urlencoded`." + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "456": { + "$ref": "#/components/responses/QuotaExceeded" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "504": { + "$ref": "#/components/responses/ServiceUnavailable" + } + }, + "security": [ + { + "auth_header": [] + } + ] + } + }, "/v2/usage": { "get": { "tags": [ diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 79f66ac1..7a1610d9 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -39,6 +39,10 @@ tags: - name: RephraseText description: |- The `rephrase` endpoint is used to make corrections and adjustments to texts based on style or tone. +- name: CorrectText + description: |- + The `correct` endpoint fixes spelling and grammar errors without broader rephrasing. Use it when you want + a minimal-change correction pass rather than the broader rewriting performed by `rephrase`. - name: ManageMultilingualGlossaries description: |- The *glossary* functions allow you to create, inspect, edit and delete glossaries. @@ -1686,7 +1690,7 @@ paths: post: tags: - RephraseText - summary: Request text improvement + summary: Improve text operationId: rephraseText requestBody: required: true @@ -1750,12 +1754,105 @@ paths: description: The language detected in the source text. type: string example: en + target_language: + description: The target language specified by the request. + type: string + example: en-US text: description: The improved text. type: string example: This is a sample sentence to improve. security: - auth_header: [ ] + /v2/write/correct: + post: + tags: + - CorrectText + summary: Correct text + description: |- + Fix spelling and grammar errors in one or more texts. Unlike `/v2/write/rephrase`, this endpoint applies + a minimal-change correction pass and does not rewrite the text for style or tone. + operationId: correctText + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - text + properties: + text: + description: Text to be corrected. Only UTF-8-encoded plain text is supported. Corrections are + returned in the same order as they are requested. + type: array + items: + type: string + example: this is a example sentence to imprve + target_lang: + $ref: '#/components/schemas/TargetLanguageWrite' + application/x-www-form-urlencoded: + schema: + type: object + required: + - text + properties: + text: + description: Text to be corrected. Only UTF-8-encoded plain text is supported. Corrections are + returned in the same order as they are requested. + type: array + items: + type: string + example: this is a example sentence to imprve + target_lang: + $ref: '#/components/schemas/TargetLanguageWrite' + responses: + 200: + description: Successful text correction. + headers: + X-Trace-ID: + $ref: '#/components/headers/X-Trace-ID' + content: + application/json: + schema: + type: object + properties: + improvements: + type: array + minItems: 1 + items: + type: object + properties: + detected_source_language: + description: The language detected in the source text. + type: string + example: en + target_language: + description: The target language specified by the request. + type: string + example: en-US + text: + description: The corrected text. + type: string + example: This is a sample sentence to improve. + 400: + $ref: '#/components/responses/BadRequest' + 403: + $ref: '#/components/responses/Forbidden' + 413: + $ref: '#/components/responses/PayloadTooLarge' + 415: + description: Unsupported Content-Type. Use `application/json` or `application/x-www-form-urlencoded`. + 429: + $ref: '#/components/responses/TooManyRequests' + 456: + $ref: '#/components/responses/QuotaExceeded' + 500: + $ref: '#/components/responses/InternalServerError' + 504: + $ref: '#/components/responses/ServiceUnavailable' + security: + - auth_header: [ ] /v2/usage: get: tags: diff --git a/docs.json b/docs.json index 94771ad2..23717225 100644 --- a/docs.json +++ b/docs.json @@ -251,7 +251,8 @@ "group": "Write", "pages": [ "api-reference/improve-text", - "api-reference/improve-text/request-text-improvement" + "api-reference/improve-text/request-text-improvement", + "api-reference/improve-text/correct-text" ] }, {