Skip to content
RunAPI Developer Docs
EN 中文
API Reference
API Reference

OpenAI Transcription Speech-to-Text

Use the speech to text endpoint to receive a result in the same response.

View Markdown
01

Overview

Use the speech to text endpoint and read the result from the same response.

Quick start

  1. Create an API key and set it as RUNAPI_API_KEY.
  2. Send a POST request whose body matches the request schema.
  3. Read the result from the successful response body.

Endpoint

POST /v1/audio/transcriptions
Base URL
https://runapi.ai
API version
v1
Authentication
Authorization: Bearer YOUR_API_TOKEN
02

Supported models

Open a model page for current pricing, rate limits, and commercial-usage details.

03

Request schema

JSON body

Send only the fields declared for this endpoint.

gpt-transcribe9 fields
filestring
Required

Audio file upload, up to 25 MB.

keywordsarray
Optional

Terms that should receive additional recognition guidance.

languagestring
Optional

Audio language as an ISO-639-1 code.

languagesarray
Optional

Candidate audio languages as ISO-639-1 codes.

modelstring
Optional

Transcription model.

Allowed values: gpt-transcribe
promptstring
Optional

Optional text that guides transcription style and vocabulary.

response_formatstring
Optional

Response body format.

Allowed values: json, text
streamboolean
Optional

Whether to request a streamed response when supported.

temperaturenumber
Optional

Sampling temperature from 0 to 1.

Range: 0 - 1
whisper-18 fields
filestring
Required

Audio file upload, up to 25 MB.

languagestring
Optional

Audio language as an ISO-639-1 code.

modelstring
Optional

Transcription model.

Allowed values: whisper-1
promptstring
Optional

Optional text that guides transcription style and vocabulary.

response_formatstring
Optional

Response body format.

Allowed values: json, text, srt, verbose_json, vtt
streamboolean
Optional

Whether to request a streamed response when supported.

temperaturenumber
Optional

Sampling temperature from 0 to 1.

Range: 0 - 1
timestamp_granularitiesarray
Optional

Timestamp detail included with verbose JSON responses.

Item limit: 2
04

Success response

HTTP 200

POST /v1/audio/transcriptions

Response schema
JSON 
{
  "oneOf": [
    {
      "properties": {
        "duration": {
          "type": "number"
        },
        "language": {
          "type": "string"
        },
        "logprobs": {
          "items": {
            "properties": {
              "bytes": {
                "items": {
                  "type": "integer"
                },
                "type": "array"
              },
              "logprob": {
                "type": "number"
              },
              "token": {
                "type": "string"
              }
            },
            "type": "object",
            "unevaluatedProperties": false
          },
          "type": "array"
        },
        "segments": {
          "items": {
            "properties": {
              "avg_logprob": {
                "type": "number"
              },
              "compression_ratio": {
                "type": "number"
              },
              "end": {
                "type": "number"
              },
              "id": {
                "type": "integer"
              },
              "no_speech_prob": {
                "type": "number"
              },
              "seek": {
                "type": "integer"
              },
              "start": {
                "type": "number"
              },
              "temperature": {
                "type": "number"
              },
              "text": {
                "type": "string"
              },
              "tokens": {
                "items": {
                  "type": "integer"
                },
                "type": "array"
              }
            },
            "type": "object",
            "unevaluatedProperties": false
          },
          "type": "array"
        },
        "task": {
          "type": "string"
        },
        "text": {
          "type": "string"
        },
        "usage": {
          "properties": {
            "input_token_details": {
              "properties": {
                "audio_tokens": {
                  "type": "integer"
                },
                "text_tokens": {
                  "type": "integer"
                }
              },
              "type": "object",
              "unevaluatedProperties": false
            },
            "input_tokens": {
              "type": "integer"
            },
            "output_tokens": {
              "type": "integer"
            },
            "seconds": {
              "type": "number"
            },
            "total_tokens": {
              "type": "integer"
            },
            "type": {
              "type": "string"
            }
          },
          "type": "object",
          "unevaluatedProperties": false
        },
        "words": {
          "items": {
            "properties": {
              "end": {
                "type": "number"
              },
              "start": {
                "type": "number"
              },
              "word": {
                "type": "string"
              }
            },
            "required": [
              "word",
              "start",
              "end"
            ],
            "type": "object",
            "unevaluatedProperties": false
          },
          "type": "array"
        }
      },
      "required": [
        "text"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "type": "string"
    }
  ]
}

Response example

JSON 
{
  "text": "Welcome to RunAPI."
}
05

Errors

HTTP 401

POST /v1/audio/transcriptions

This response has no body.

06

Errors

HTTP 400

POST /v1/audio/transcriptions

Response schema
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "error": {
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": {
    "code": "model_must_be_one_of_gpt-transcribe_whisper-1",
    "message": "model must be one of: gpt-transcribe, whisper-1"
  }
}
07

Errors

HTTP 402

POST /v1/audio/transcriptions

Response schema
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "error": {
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance"
  }
}
08

Errors

HTTP 403

POST /v1/audio/transcriptions

Response schema
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "error": {
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": {
    "code": "api_token_credit_limit_exceeded",
    "message": "API key credit limit exceeded"
  }
}
09

Errors

HTTP 409

POST /v1/audio/transcriptions

Response schema
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "error": {
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": {
    "code": "request_conflict",
    "message": "The request uses features that are not supported for the selected model"
  }
}
10

Errors

HTTP 429

POST /v1/audio/transcriptions

Response schema
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "error": {
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit reached. Please retry later."
  }
}
11

Errors

HTTP 503

POST /v1/audio/transcriptions

Response schema
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "error": {
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": {
    "code": "service_unavailable",
    "message": "Service under maintenance, please try again later"
  }
}
12

Errors

HTTP 504

POST /v1/audio/transcriptions

Response schema
JSON 
{
  "properties": {
    "billing": {
      "properties": {
        "refund": {
          "oneOf": [
            {
              "properties": {
                "refunded_at": {
                  "type": "string"
                }
              },
              "required": [
                "refunded_at"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "reservation": {
          "oneOf": [
            {
              "properties": {
                "amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "amount_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        },
        "settlement": {
          "oneOf": [
            {
              "properties": {
                "amount_micro_cents": {
                  "type": "integer"
                },
                "charged_amount_cents": {
                  "type": "integer"
                }
              },
              "required": [
                "charged_amount_cents",
                "amount_micro_cents"
              ],
              "type": "object",
              "unevaluatedProperties": false
            },
            {
              "enum": [
                null
              ]
            }
          ]
        }
      },
      "required": [
        "reservation",
        "settlement",
        "refund"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    "error": {
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "error": {
    "code": "timeout_error",
    "message": "The request timed out"
  }
}
13

Generated Code Samples

Use cURL directly, or install an SDK for your language. Each sample submits the validated request shown in this reference.

CURL 
curl -X POST https://runapi.ai/v1/audio/transcriptions \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"file":"audio.mp3","model":"whisper-1","response_format":"json"}'

Install

BASH 
npm install @runapi.ai/openai-transcription
JAVASCRIPT 
import { OpenaiTranscriptionClient } from "@runapi.ai/openai-transcription";

const client = new OpenaiTranscriptionClient({ apiKey: process.env.RUNAPI_API_KEY });
const result = await client.speechToText.run({
  "file": "audio.mp3",
  "model": "whisper-1",
  "response_format": "json"
});

Install

BASH 
pip install runapi-openai-transcription
PYTHON 
import os
from runapi.openai_transcription import OpenaiTranscriptionClient

client = OpenaiTranscriptionClient(api_key=os.environ["RUNAPI_API_KEY"])
result = client.speech_to_text.run(
  file="audio.mp3",
  model="whisper-1",
  response_format="json"
)

Install

BASH 
go get github.com/runapi-ai/openai-transcription-sdk/go@latest
GO 
package main

import (
  "context"
  "log"
  "os"

  "github.com/runapi-ai/core-sdk/go/option"
  openaitranscription "github.com/runapi-ai/openai-transcription-sdk/go/openaitranscription"
)

func main() {
  client, err := openaitranscription.NewClient(option.WithAPIKey(os.Getenv("RUNAPI_API_KEY")))
  if err != nil {
    log.Fatal(err)
  }

  result, err := client.SpeechToText.Run(context.Background(), openaitranscription.SpeechToTextParams{
    File: "audio.mp3",
    Model: "whisper-1",
    ResponseFormat: "json",
  })
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

Install

BASH 
gem install runapi-openai-transcription
RUBY 
require "runapi/openai_transcription"

client = RunApi::OpenaiTranscription::Client.new(api_key: ENV.fetch("RUNAPI_API_KEY"))
result = client.speech_to_text.run(
  file: "audio.mp3",
  model: "whisper-1",
  response_format: "json"
)

Install

KOTLIN 
implementation("ai.runapi:runapi-openai-transcription")
JAVA 
import ai.runapi.openaitranscription.OpenaiTranscriptionClient;
import ai.runapi.openaitranscription.types.SpeechToTextParams;
import ai.runapi.openaitranscription.types.TranscriptionResponse;

public final class Example {
  public static void main(String[] args) {
    OpenaiTranscriptionClient client = OpenaiTranscriptionClient.builder()
        .apiKey(System.getenv("RUNAPI_API_KEY"))
        .build();
    TranscriptionResponse result = client.speechToText().run(
        SpeechToTextParams.builder()
        .file("audio.mp3")
        .model("whisper-1")
        .responseFormat("json")
            .build()
    );
  }
}

Install

BASH 
composer require runapi-ai/openai-transcription
PHP 
<?php

require __DIR__ . '/vendor/autoload.php';

use RunApi\Core\ClientOptions;
use RunApi\OpenaiTranscription\OpenaiTranscriptionClient;

$client = new OpenaiTranscriptionClient(new ClientOptions(apiKey: getenv('RUNAPI_API_KEY')));
$result = $client->speechToText->run([
  "file" => "audio.mp3",
  "model" => "whisper-1",
  "response_format" => "json"
]);