Software developers studying pronunciation API documentation

Designed by pikisuperstar / Freepik

About this API

thefluent.me is an API for AI-powered pronunciation scoring, translation, and voice generation for 40+ languages. The API provides:

  1. Overall (per recording) pronunciation scoring of recordings up to 60 seconds;
  2. Word-level (per word) pronunciation scoring: A pronunciation score for each word;
  3. You can choose the scoring scale (e.g., 0-90 points);
  4. Reading speed evaluation: Feedback on the user’s reading speed for each word;
  5. Translate any text into any of the supported languages;
  6. Instant voice generation: Users can listen to a post while practicing. You can choose from ore than 80 voices;
  7. Metadata that helps the users track their progress and build a user profile for data-driven suggestions.

All you need to provide is:
  1. A short text (post) of up to 1,000 characters;
  2. 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

Try on RapidAPI Try Swagger UI

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
  1. language_id: The id for the post language
  2. language_name: The name of the post language
  3. language_voice: The name of the voice for the ai_reading
 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

Try on RapidAPI Try Swagger UI

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

Add post

Try on RapidAPI Try Swagger UI

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
  1. original post if it is a new post or
  2. the post_id of the original post if it is a translated post (e.g. P123456)
 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

Try on RapidAPI Try Swagger UI

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
  1. page: The current page number
  2. per_page: The number of posts per page
  3. total_pages: The total number of pages, depending on the given ‘per_page’ value
  4. total_posts: The total number of posts in the database
 array
posts
  1. ai_reading: The URL for the sound file generated by the AI, based on the post_content provided
  2. date_posted: The date the post was added
  3. post_content: The actual text of the post
  4. post_id: The id of the post
  5. post_language_id: The language id of the post
  6. post_language_name: The post language name
  7. post_language_voice: The voice name for the ai_reading
  8. post_source: The value will be either
    1. The string 'original post' if it is a new post or
    2. the post_id of the original post if it is a translated post (e.g. P123456)
  9. post_title: The title provided for the post
 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

Try on RapidAPI Try Swagger UI

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
  1. original post if it is a new post or
  2. the post_id of the original post if it is a translated post (e.g. P123456)
 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

Try on RapidAPI Try Swagger UI

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
  1. original post if it is a new post or
  2. the post_id of the original post if it is a translated post (e.g. P123456)
 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

Try on RapidAPI Try Swagger UI

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

Try on RapidAPI Try Swagger UI

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

Score

Try on RapidAPI Try Swagger UI

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
  1. audio_provided: New URL for the provided audio. Please note: the audio file you provide in your request was copied to our server. The file is only accessible through the signed URL generated with this API call. It expires after 5 minutes. You can generate new signed URLs for this score using the Get all scores or Get score by id calls. These URLs also expire after 5 minutes.
  2. post_provided: the text provided
 array
overall_result_data
  1. ai_reading: The URL for the sound file generated by the AI, based on the post_content provided
  2. length_of_recording_in_sec: The length of the recording provided in seconds
  3. number_of_recognized_words: The number of words the AI recognized
  4. number_of_words_in_post: The total number of words of the provided post
  5. overall_points: The overall scoring of the recording expressed in points from 0-90. Please note: this is not the average of the word_result_data scores. It is based on a specific algorithm developed for this API.
  6. post_language_id: The language id of this score
  7. post_language_name: The language name of this score
  8. score_id: The database id of this score
  9. user_resording_transcript: The URL for the recording provided
 array
Word_result_data (for each word)
  1. points: The word-level score, expressed in points, for the pronunciation of this word
  2. speed: The classification of the reading speed of this word. Please note: this classification is not based on a metric such as characters per second. It is based on an algorithm developed for this API. Returned values are
    1. good
    2. slow
    3. fast
    4. not available
  3. Word: The actual 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

Try on RapidAPI Try Swagger UI

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
  1. page: The current page number
  2. per_page: The number of posts per page
  3. total_pages: The total number of pages, depending on the given ‘per_page’ value
  4. total_scores: The total number of scores in the database
 array
scores
  1. ai_reading: The URL for the sound file generated by the AI, based on the post_content provided
  2. audio_provided: The URL for the provided audio. Please note: the audio file you provide in your initial Score request was copied to our server. The file is only accessible through a signed URL generated with this API call or the Get score by id call. This URL expires after 5 minutes. You can generate new signed URLs for this score using this API call or the Get score by id call.
  3. length_of_recording_in_sec: The length of the recording provided in seconds
  4. number_of_recognized_words: The number of words the AI recognized
  5. number_of_words_in_post: The total number of words of the provided post
  6. overall_points: The overall scoring of the recording expressed in points from 0-90. Please note: this is not the average of the word_result_data scores. It is based on a specific algorithm developed for this API.
  7. post_language_id: The language id of the post
  8. post_language_name: The language name of the post
  9. post_provided: The text provided
  10. post_title: The title provided for the post
  11. score_date: The date of the scoring
  12. score_id: The id of the score
  13. user_recording_transcript: The transcript of the audio_provided file
 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

Try on RapidAPI Try Swagger UI

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
  1. ai_reading: URL for the sound file generated by the AI, based on the post_content provided
  2. audio_provided: The URL for the provided audio. Please note: the audio file you provide in your initial Score request was copied to our server. The file is only accessible through a signed URL generated with this API call or the Get all scores call. This URL expires after 5 minutes. You can generate new signed URLs for this score using this API call or the Get all scores call.
  3. length_of_recording_in_sec: length of the recording provided in seconds
  4. number_of_recognized_words: number of words the AI recognized
  5. number_of_words_in_post: total number of words of the provided post
  6. overall_points: the overall scoring of the recording expressed in points from 0-90. Please note: this is not the average of the word_result_data scores. It is based on a specific algorithm developed for this API.
  7. post_language_id: the id of the score language
  8. post_language_name: the name of the score language
  9. post_provided: the text provided
  10. post_title: the title provided for the post
  11. score_date: the date of the scoring
  12. score_id: the database id of the score
  13. user_recording_transcript: the transcript of the audio_provided file
 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

Try on RapidAPI Try Swagger UI

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