About this API
thefluent.me is an API for AI-powered pronunciation scoring, translation, and voice generation for 40+ languages. The API provides:
- Overall (per recording) pronunciation scoring of recordings up to 60 seconds;
- Word-level (per word) pronunciation scoring: A pronunciation score for each word;
- You can choose the scoring scale (e.g., 0-90 points);
- Reading speed evaluation: Feedback on the user’s reading speed for each word;
- Translate any text into any of the supported languages;
- Instant voice generation: Users can listen to a post while practicing. You can choose from ore than 80 voices;
- Metadata that helps the users track their progress and build a user profile for data-driven suggestions.
All you need to provide is:
- A short text (post) of up to 1,000 characters;
- The URL for the audio file of the recording.
You can test the API for free on RapidAPI or our Swagger UI
All you need is a free account on RapidAPI. If you prefer our Swagger UI sign up for your API key here please
Live demo
Please visit https://thefluent.me (this app) for a live demo.
Get all languages
Returns a list of supported languages/ voices.
Get all languages | Endpoint
Endpoint | Description | Method |
---|---|---|
/language | application/json | GET |
Get all languages | Sample request
/language
Get all languages | Success response
Array name | Description | Type |
---|---|---|
supported_languages |
|
array |
Get all languages | Sample success response
{
"supported_languages": [
{
"language_id": 22,
"language_name": "English",
"language_voice": "English (Australia) - female voice",
},
{
"language_id": 47,
"language_name": "Korean",
"language_voice": "Korean (South Korea) - female voice",
}
]
}
Get language by id
Returns a language by id.
Returns a language by id | Endpoint
Endpoint | Description | Method |
---|---|---|
/language/{language_id} | application/json | GET |
Get language by id | Sample request
/language/58
Get language by id | Success response
Name | Description | Type |
---|---|---|
language_id | The language id | integer |
language_name | The language name | string |
language_voice | The voice for the AI sound file | string |
Get language by id | Sample success response
{
"language_id": 58,
"language_name": "Punjabi",
"language_voice": "Punjabi (India) - female voice",
}
Get language by id | Error responses
Scenario | Error message | Code |
---|---|---|
Wrong language_id provided | Language not found. | 404 |
Generate post
Generate posts using ChatGPT. This endpoint returns a post based on the title you provide and the length you would like the post to be. You can also select different AI models. This service is available in English. Please note: Generated posts are not saved in our database. Please refer to Add post to save posts in our database.
Tips for working with this endpoint
- More specific post titles will provide better responses. ChatGPT tends to complete the title you provide. For instance, if your post_title would just be 'Environment', the generated post could start with 'variable', followed by one or more complete sentences. If you would provide a post_title 'What does Environment mean?' your post will most likely start with a complete sentence.
- Currently, two AI models are supported. The regular_01 model is faster, but provides simpler (and mostly shorter) posts. The advanced_01 model provides high-quality posts but is slower. If this parameter is not provided, the regular_01 model is used.
- The length of the generated post depends on the parameters post_min_length and post_max_length. If the difference between these values (range) is smaller, ChatGPT might not be able to generate a post for you. In this case the response will be an error code 416.
Generate post | Endpoint
Endpoint | Description | Method |
---|---|---|
/generate-post | application/json | POST |
Generate post | Sample request
/generate-post
Generate post | Request body parameters
Parameter name | Description | Required |
---|---|---|
post_title | The post_title generates the ChatGPT response. The post_title can be between 3 and 100 characters long. | yes |
ai_model | Allowed values are regular_01 and advanced_01. If this value is not provided regular_01 is used. | no |
post_min_length | Defines the minimum length of the post in characters, including spaces. Must be an integer between 1-1000. If this parameter is not provided, 1 is used. | no |
post_max_length | Defines the maximum length of the post in characters, including spaces. Must be an integer between 1-1000. If this parameter is not provided, 500 is used. | no |
Generate post | Sample request body
{
"post_title": "What does environment mean?",
"ai_model": "regular_01",
"post_min_length": 150,
"post_max_length": 400
}
Generate post | Success response
Name | Description | Type |
---|---|---|
ai_post | The post created by ChatGPT. | string |
post_length | The length of the post in characters including spaces. | integer |
post_title | The post_title provided in the request | string |
Generate post | Sample success response
{
"ai_post": "Environment is a term used to describe the surroundings (...) and quality of life.",
"post_length": 352,
"post_title": "What does environment mean?",
}
Generate post | Error responses
Scenario | Error message | Code |
---|---|---|
The post_title was not provided | Please provide a post_title. | 400 |
The post_title is too short | The title is too short. The minimum length is 3 characters. | 400 |
The post_title is too long | The title is too long. The maximum length is 100 characters. | 400 |
The ai_model value provided is not correct | Please provide a valid ai_model. Valid model names are 'regular_01' and 'advanced_01'. | 400 |
The post_min_length value provided is not valid | Please provide a valid integer for 'post_min_length'. | 400 |
The post_max_length value provided is not valid | Please provide a valid integer for 'post_max_length'. | 400 |
The post_min_length value provided is greater than the post_max_value provided | The 'post_max_length' should be greater than or equal to 'post_min_length'. | 400 |
ChatGPT could not create a post with the given parameters. | Could not generate a post. Please adjust the values for 'post_min_length' and 'post_max_length'. | 416 |
Add post
Add a new post of up to 1,000 characters, including whitespaces. The AI automatically generates a sound file (ai_reading) so users can listen to the post. Therefore the response can take up to 30 seconds, depending on the length of your post.
Add post | Endpoint
Endpoint | Description | Method |
---|---|---|
/post | application/json | POST |
Add post | Sample request
/post
Add post | Request body parameters
Parameter name | Description | Required |
---|---|---|
post_language_id | The post_language_id defines the post language. The AI generates a sound file based on the text provided, so users can listen to it while practicing. You can choose from over 80 voices representing over 40 languages. | yes |
post_title | Between 3-100 characters | yes |
post_content | Between 3-1000 characters | yes |
Add post | Sample request body
{
"post_language_id": "22",
"post_title": "This is a test title",
"post_content": "Here is a test post content."
}
Add post | Success response
Name | Description | Type |
---|---|---|
ai_reading | URL for the sound file generated by the AI, based on the post_content provided. If you need a test file simply go to https://thefluent.me, click Read Aloud, and download your recording. | string |
date_posted | The date the post was added | date |
post_content | The actual text of the post | string |
post_id | The id of the post | string |
post_language_id | The id for the post language and voice | integer |
post_language_name | The post language name | string |
post_language_voice | The voice for the ai_reading | string |
post_source | The value will be either
|
string |
post_title | The title provided for the post | string |
Add post | Sample success response
{
"ai_reading": "https://storage.googleapis.com/thefluentme.appspot.com/audio/generated/20210801-203322-12345-generated.mp3",
"date_posted": "Mon, 22 Feb 2022 03:33:22 GMT",
"post_content": "Here is a test post content.",
"post_id": "P5640903",
"post_language_id": "22",
"post_language_name": "English",
"post_language_voice": "English (US) - female voice",
"post_source": "original post",
"post_title": "This is a test title"
}
Add post | Error responses
Scenario | Error message | Code |
---|---|---|
One or more parameters are not provided | Please provide a valid post_language_id, post_title, post_content. | 400 |
The post_title is too short | The title is too short. The minimum length is 3 characters. | 400 |
The post_title is too long | The title is too long. The maximum length is 100 characters. | 400 |
The post_content is too short | The post_content is too short. The minimum length is 3 characters. | 400 |
The post_content is too long | The post_content is too long. The maximum length is 1000 characters. | 400 |
Get all posts
Returns a paginated list of posts.
Get all posts | Endpoint
Endpoint | Description | Method |
---|---|---|
/post?{page}&{per_page} | application/json | GET |
Get all posts | Request query parameters
Name | Description | Required |
---|---|---|
page | Integer. If no value is provided, the default value of 1 will be applied. | no |
per_page | Integer. If no value is provided, the default value of 10 will be applied. | no |
Get all posts | Sample request
/post?page=1&per_page=5
The result would be the first page showing five posts.
Get all posts | Success response
Array name | Description | Type |
---|---|---|
post_data |
|
array |
posts |
|
array |
Get all posts | Sample success response
[
{
"post_data": [
{
"page": 1,
"per_page": 5,
"total_pages": 4,
"total_posts": 20
}
]
},
{
"posts": [
{
"ai_reading": "https://storage.googleapis.com/thefluentme.appspot.com/audio/generated/f-20210801-161109-23456-generated.mp3",
"date_posted": "Sun, 03 Oct 2021 13:11:09 GMT",
"post_content": "Here is post contet one",
"post_id": "P8930191",
"post_language_id": "22",
"post_language_name": "English",
"post_language_voice": "English (US) - female voice",
"post_source": "original post",
"post_title": "This is title one"
},
{
"ai_reading": "https://storage.googleapis.com/thefluentme.appspot.com/audio/generated/f-20210801-202953-56789-generated.mp3",
"date_posted": "Mon, 03 Oct 2021 15:29:53 GMT",
"post_content": "Hier ist der erste Beitrag",
"post_id": "P4054732",
"post_language_id": "31",
"post_language_name": "German",
"post_language_voice": "German (Germany) - male voice",
"post_source": "P123456",
"post_title": "Dies ist Beitrag eins"
}
]
}
]
Get all posts | Error responses
Scenario | Error message | Code |
---|---|---|
Value for request parameter ‘page’ larger than the total number of pages | No results found because the value for ‘page’ in your request is <page> and the total number of pages is <total_pages>. | 400 |
Get post by id
Returns a post by post_id.
Get post by id | Endpoint
Endpoint | Description | Method |
---|---|---|
/post/{post_id} | application/json | GET |
Get post by id | Sample request
/post/P123456
Get post by id | Success response
Name | Description | Type |
---|---|---|
ai_reading | The URL for the sound file generated by the AI, based on the post_content provided | string |
date_posted | The date the post was added | string |
post_content | The actual text of the post | string |
post_id | The id of the post | string |
post_language_id | The language id of the post | integer |
post_language_name | The post language name | string |
post_language_voice | The voice name for the ai_reading | string |
post_source | The value will be either
|
string |
post_title | The title provided for the post | string |
Get post by id | Sample success response
{
"ai_reading": "https://storage.googleapis.com/thefluentme.appspot.com/audio/generated/f-20210801-161109-23456-generated.mp3",
"date_posted": "Sun, 01 Aug 2021 13:11:09 GMT",
"post_content": "Hier ist der eigentliche Beitrag",
"post_id": "P8930191",
"post_language_id": 30,
"post_language_name": "German",
"post_language_voice": "German (Germany) - female voice",
"post_source": "P123456",
"post_title": "Das ist Beitrag eins"
}
Get post by id | Error responses
Scenario | Error message | Code |
---|---|---|
Wrong post_id provided | Post not found | 404 |
Update post
Update post by post_id
Update post | Endpoint
Endpoint | Description | Method |
---|---|---|
/post/{post_id} | application/json | PUT |
Update post | Sample request
/post/P123456
Update post | Request body parameters
Parameter name | Description | Required |
---|---|---|
post_language_id | The post_language_id defines the post language. The AI generates a sound file based on the text provided, so users can listen to it while practicing. You can choose from over 80 voices representing over 40 languages. | yes |
post_title | Between 3-100 characters | yes |
post_content | Between 3-1000 characters | yes |
Update post | Sample request
{
"post_language_id": "22",
"post_title": "This is a test title",
"post_content": "Here is a test post content."
}
Update post | Success response
Name | Description | Type |
---|---|---|
ai_reading | URL for the sound file generated by the AI, based on the post_content provided. | string |
date_posted | Date the post was added | date |
post_content | The actual text of the post | string |
post_id | Id of the post | string |
post_language_id | The id for the post language and voice | integer |
post_language_name | The post language name | string |
post_language_voice | The voice for the ai_reading | string |
post_source | The value will be either
|
string |
post_title | The title provided for the post | string |
Add post | Sample success response
{
"ai_reading": "https://storage.googleapis.com/thefluentme.appspot.com/audio/generated/20210801-203322-12345-generated.mp3",
"date_posted": "Mon, 22 Feb 2022 03:33:22 GMT",
"post_content": "Here is a test post content.",
"post_id": "P5640903",
"post_language_id": "22",
"post_language_name": "English",
"post_language_voice": "English (US) - female voice",
"post_source": "original post",
"post_title": "This is a test title"
}
Add post | Error responses
Scenario | Error message | Code |
---|---|---|
One or more parameters are not provided | Please provide a valid post_language_id, post_title, post_content. | 400 |
The post_title is too short | The title is too short. The minimum length is 3 characters. | 400 |
The post_title is too long | The title is too long. The maximum length is 100 characters. | 400 |
The post_content is too short | The post_content is too short. The minimum length is 3 characters. | 400 |
The post_content is too long | The post_content is too long. The maximum length is 1000 characters. | 400 |
Delete post
Delete post by post_id.
Delete post | Endpoint
Endpoint | Description | Method |
---|---|---|
/post/{post_id} | application/json | DELETE |
Delete post | Sample request
/post/P123456
Delete post | Success response
Name | Description | Type |
---|---|---|
message | The post has been deleted! | string |
Delete post | Error responses
Scenario | Error message | Code |
---|---|---|
Wrong post_id provided | Post not found | 404 |
Translate post
Translate post into any supported language.
Translate post | Endpoint
Endpoint | Description | Method |
---|---|---|
/translate/{post_id} | application/json | POST |
Translate post | Sample request
/translate/P123456
Translate post | Request body parameters
Name | Description | Required |
---|---|---|
target_language_id | The language id of the language the post will be translated into. | yes |
Translate post | Sample request body
{
"target_language_id": "22"
}
Translate post | Success response
Name | Description | Type |
---|---|---|
post_language_id | The language id | integer |
date_posted | The date the translated post was added | date |
ai_reading | The URL for the sound file generated by the AI, based on the post_content provided | string |
post_content | The actual text of the post | string |
post_id | The id of the post | string |
post_language_name | The language name | string |
post_language_voice | The voice for the AI sound file | string |
post_source | The id of the original post | string |
post_title | The headline of the post | string |
Translate post | Sample success response
{
"post_language_id": 22,
"date_posted": "Mon, 20 Feb 2022 03:33:22 GMT",
"ai_reading": "https://storage.googleapis.com/thefluentme.appspot.com/audio/generated/f-20210801-203322-12345-generated.mp3",
"post_content": "This is an example post. The post can be between three and 1000 characters long.",
"post_id": "P5640903",
"post_language_name": "English",
"post_language_voice": "English (US) - female voice",
"post_source": "P5212687",
"post_title": "My first post title",
}
Translate post | Error responses
Senario | Error message | Code |
---|---|---|
Invalid value for target_language_id | Please provide a valid target_language_id | 400 |
Invalid value for post_id | Post not found | 404 |
Returns the reading score of the user recording.
The API supports different sound file formats such as .wav or .mp3. More information on supported audio file formats and encodings can be found here: https://cloud.google.com/speech-to-text/docs/encoding#audio-encodings. The maximum recording length is 60 seconds.
If you need a test sound file visit https://thefluent.me, click Read Aloud and download the .wav file after you finsih recording.
Score | Endpoint
Endpoint | Description | Method |
---|---|---|
/score/{post_id}?{scale} | application/json | POST |
Score | Sample request URL
/score/S234567?scale=90
The scale parameter defines the maximum number of points for the recording, as well as each word. This parameter is not required. The default value of 100 will be applied if the parameter is not provided. The result of the example above would be the score for post_id S234567 with an overall score and word-level scores on a scale from 0-90 points.
Score | Request body parameters
Name | Description | Required |
---|---|---|
audio_provided | URL for the audio file. | yes |
Score | Sample request body
{
"audio_provided": "https://storage.googleapis.com/thefluentme.appspot.com/audio/api/recorded/TestApiKey-thefluentme-0921101-20210908-165907-90279-recorded-audio.wav"
}
Score | Success response
Array name | Description | Type |
---|---|---|
provided_data |
|
array |
overall_result_data |
|
array |
Word_result_data (for each word) |
|
array |
Score | Sample response
[
{
"provided_data": [
{
"audio_provided": "https://storage.googleapis.com/thefluentmeprod01/audio/api/recorded/20220603215157-fQaj7AdeKhp-52519-20220604-145317-56053-recorded-audio.wav?Expires=1654379666&GoogleAccessId=thefluentme%40appspot.gserviceaccount.com&Signature=WaSSW0%2FhqAJlH8OwFUuzrcm1q2K8TlJOkrFThlMhMhZ8Px1AZ7Oyq...g%3D%3D",
"post_provided": "Post content number one."
}
]
},
{
"overall_result_data": [
{
"ai_reading": "https://storage.googleapis.com/thefluentme.appspot.com/audio/api/generated/Group_Id_1-f-20210905-230210-86603-generated.mp3",
"length_of_recording_in_sec": 2.9,
"number_of_recognized_words": 3,
"number_of_words_in_post": 4,
"overall_points": 53.32675948739052,
"post_language_id": 22,
"post_language_name": "English",
"score_id": "S59153",
"user_recording_transcript": "Post content number one."
}
]
},
{
"word_result_data": [
{
"points": "64.45898523545414",
"speed": "good",
"word": "Post"
},
{
"points": "64.54871234568745",
"speed": "fast",
"word": "content"
},
{
"points": "36.45712468223147",
"speed": "slow",
"word": "number"
},
{
"points": "0.0",
"speed": "not_available",
"word": "one”
}
]
}
]
Score | Error responses
Senario | Error message | Code |
---|---|---|
The URL for the key ‘audio_recorded’ is not valid |
Please note the maximum recording length is 60 seconds and the URL and audio format must be valid. More information on supported audio file formats and encodings can be found here: https://cloud.google.com/speech-to-text/docs/encoding#audio-encodings
If you need a test sound file visit https://thefluent.me, click Read Aloud and download the .wav file after you finsih recording. |
400 |
Invalid value for post_id | Post not found | 404 |
Get all scores
Returns a paginated list of scores
Get all scores | Endpoint
Endpoint | Description | Method |
---|---|---|
/score?{page}&{per_page}&{scale} | application/json | GET |
Get all scores | Sample request
/score?page=1&per_page=10&scale=90
The scale parameter defines the maximum number of points for the recording as well as each word. This parameter is not required. The default value of 100 will be applied if the parameter is not provided.
The result would be the first 10 scores with scores on a scale from 0-90 points.
Get all scores | Request query parameters
Name | Description | Required |
---|---|---|
page | Integer. If no value is provided, the default value of 1 will be applied. | no |
per_page | Integer. If no value is provided, the default value of 10 will be applied. | no |
Get all scores | Success response
Name | Description | Type |
---|---|---|
score_data |
|
array |
scores |
|
array |
Get all scores | Sample responses
[
{
"score_data": [
{
"page": 1,
"per_page": 10,
"total_pages": 25,
"total_scores": 241
}
]
},
{
"scores": [
{
"ai_reading": "https://storage.googleapis.com/thefluentme.appspot.com/audio/api/generated/user.name-f-20210928-023933-83821-generated.mp3",
"audio_provided": "https://storage.googleapis.com/thefluentmeprod01/audio/api/recorded/20220605133400-fQaj7AdeKhp-36749-20220605-134601-32520-recorded-audio.wav?Expires=1654462863&GoogleAccessId=thefluentme%40appspot.gserviceaccount.com&Signature=L3%2BKnz1cyvyTHoc1CdypJRxphw1oF%2B6...Grw%3D%3D",
"length_of_recording_in_sec": 10.1,
"number_of_recognized_words": 10,
"number_of_words_in_post": 14,
"overall_points": 64.969240000000003,
"post_language_id": S123456,
"post_language_name": "English",
"post_provided": "This is the first example post. The post is here as an example only",
"post_title": "Test post one",
"score_date": "Tue, 28 Sep 2021 02:53:13 GMT",
"score_id": "S53132215",
"user_recording_transcript": "This is a first example host. The post is hear as a example only."
},
{
"ai_reading": "https://storage.googleapis.com/thefluentme.appspot.com/audio/api/generated/markus.koy-f-20210928-023952-13395-generated.mp3",
"audio_provided": "https://storage.googleapis.com/thefluentme.appspot.com/audio/api/recorded/markus.koy-20210928-025416-64253-recorded-audio.wav",
"length_of_recording_in_sec": 8.9,
"number_of_recognized_words": 13,
"number_of_words_in_post": 14,
"overall_points": 79.05656566,
"post_language_id": S234567,
"post_language_name": "German",
"post_provided": "Hier ist ein Beispiel Post.",
"post_title": "Beitrag Titel",
"score_date": "Tue, 28 Sep 2021 02:54:22 GMT",
"score_id": "S54222216",
"user_recording_transcript": "This is the seconds example post. The post is here as an example only"
}
]
}
]
Get all scores | Error responses
Senario | Error message | Code |
---|---|---|
Value for request parameter ‘page’ larger than the total number of pages | No results found because the value for ‘page’ in your request is <page> and the total number of pages is <total_pages>. | 400 |
Get score by id
Get score by score_id.
Get score by id | Endpoint
Endpoint | Description | Method |
---|---|---|
/score/{score_id}?{scale} | application/json | GET |
Get score by id | Sample request
/score/S234567?scale=90
The scale parameter defines the maximum number of points for the recording, as well as each word. This parameter is not required. The default value of 100 will be applied if the parameter is not provided.
Get score by id | Request query parameter
Name | Description | Required |
---|---|---|
scale | Integer. If no value is provided, the default value of 100 will be applied. | No |
Get score by id | Success response
Name | Description | Type |
---|---|---|
score |
|
array |
Get score by id | Sample response
{
"score": {
"ai_reading": "https://storage.googleapis.com/thefluentme.appspot.com/audio/api/generated/Group_Id_1-f-20210905-230210-86603-generated.mp3",
"audio_provided": "https://storage.googleapis.com/thefluentmeprod01/audio/api/recorded/20220605133400-fQaj7AdeKhp-36749-20220605-134601-32520-recorded-audio.wav?Expires=1654462863&GoogleAccessId=thefluentme%40appspot.gserviceaccount.com&Signature=L3%2BKnz1cyvyTHoc1Cd...zGrw%3D%3D",
"length_of_recording_in_sec": 3.9,
"number_of_recognized_words": 4,
"number_of_words_in_post": 8,
"overall_points": 33.32675948739052,
"post_language_id": 22,
"post_language_name": "English",
"post_provided": "This is the original post",
"post_title": "Post title one",
"score_date": "Wed, 08 Sep 2021 23:59:15 GMT",
"score_id": "S59153",
"user_recording_transcript": "This is the user transcript."
}
Get one score | Error response
Senario | Error message | Code |
---|---|---|
Wrong score_id provided | Score not found | 404 |
Delete score
Delete score by score_id.
Delete score | Endpoint
Endpoint | Description | Method |
---|---|---|
/score/{score_id} | application/json | DELETE |
Delete score | Sample request
/score/S234567
Delete score | Success response
Name | Description | Type |
---|---|---|
message | The score has been deleted! | String |
Delete score | Error response
Scenario | Error message | Code |
---|---|---|
Wrong score_id provided | Score not found | 404 |