--- title: OpenAI Transcription Speech-to-Text url: https://runapi.ai/zh-CN/docs/api/openai-transcription/speech-to-text.md canonical: https://runapi.ai/zh-CN/docs/api/openai-transcription/speech-to-text locale: zh-CN --- # OpenAI Transcription Speech-to-Text ## 概览 提交Speech to Text请求，并直接使用同一响应返回的结果。 ### 快速开始 1. 创建 API Key，并将其设置为 RUNAPI_API_KEY。 2. 发送与请求 Schema 匹配的 POST 请求。 3. 从成功响应正文中读取结果。 ## 端点 POST /v1/audio/transcriptions 基础 URL: https://runapi.ai API 版本: v1 身份验证: Authorization: Bearer YOUR_API_TOKEN ## 支持的模型 打开模型页可查看当前价格、限流和商业使用详情。 - [gpt-transcribe](/models/openai-transcription/gpt-transcribe) - [whisper-1](/models/openai-transcription/whisper-1) ## 请求 Schema 只发送此端点声明的字段。 ### gpt-transcribe ```json { "file": { "description": "Audio file upload, up to 25 MB.", "required": true, "type": "string" }, "keywords": { "description": "Terms that should receive additional recognition guidance.", "items": { "type": "string" }, "type": "array" }, "language": { "description": "Audio language as an ISO-639-1 code.", "type": "string" }, "languages": { "description": "Candidate audio languages as ISO-639-1 codes.", "items": { "type": "string" }, "type": "array" }, "model": { "description": "Transcription model.", "enum": [ "gpt-transcribe" ], "type": "string" }, "prompt": { "description": "Optional text that guides transcription style and vocabulary.", "type": "string" }, "response_format": { "description": "Response body format.", "enum": [ "json", "text" ], "type": "string" }, "stream": { "description": "Whether to request a streamed response when supported.", "type": "boolean" }, "temperature": { "description": "Sampling temperature from 0 to 1.", "max": 1, "min": 0, "type": "number" } } ``` ### whisper-1 ```json { "file": { "description": "Audio file upload, up to 25 MB.", "required": true, "type": "string" }, "language": { "description": "Audio language as an ISO-639-1 code.", "type": "string" }, "model": { "description": "Transcription model.", "enum": [ "whisper-1" ], "type": "string" }, "prompt": { "description": "Optional text that guides transcription style and vocabulary.", "type": "string" }, "response_format": { "description": "Response body format.", "enum": [ "json", "text", "srt", "verbose_json", "vtt" ], "type": "string" }, "stream": { "description": "Whether to request a streamed response when supported.", "type": "boolean" }, "temperature": { "description": "Sampling temperature from 0 to 1.", "max": 1, "min": 0, "type": "number" }, "timestamp_granularities": { "description": "Timestamp detail included with verbose JSON responses.", "items": { "enum": [ "word", "segment" ], "type": "string" }, "max_items": 2, "type": "array" } } ``` ## 成功响应 HTTP 200 - POST /v1/audio/transcriptions ### 响应 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" } ] } ``` ### 响应示例 ```json { "text": "Welcome to RunAPI." } ``` ## 错误 HTTP 401 - POST /v1/audio/transcriptions 此响应不包含正文。 ## 错误 HTTP 400 - POST /v1/audio/transcriptions ### 响应 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 } ``` ### 响应示例 ```json { "error": { "code": "model_must_be_one_of_gpt-transcribe_whisper-1", "message": "model must be one of: gpt-transcribe, whisper-1" } } ``` ## 错误 HTTP 402 - POST /v1/audio/transcriptions ### 响应 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 } ``` ### 响应示例 ```json { "error": { "code": "insufficient_balance", "message": "Insufficient balance" } } ``` ## 错误 HTTP 403 - POST /v1/audio/transcriptions ### 响应 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 } ``` ### 响应示例 ```json { "error": { "code": "api_token_credit_limit_exceeded", "message": "API key credit limit exceeded" } } ``` ## 错误 HTTP 409 - POST /v1/audio/transcriptions ### 响应 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 } ``` ### 响应示例 ```json { "error": { "code": "request_conflict", "message": "The request uses features that are not supported for the selected model" } } ``` ## 错误 HTTP 429 - POST /v1/audio/transcriptions ### 响应 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 } ``` ### 响应示例 ```json { "error": { "code": "rate_limited", "message": "Rate limit reached. Please retry later." } } ``` ## 错误 HTTP 503 - POST /v1/audio/transcriptions ### 响应 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 } ``` ### 响应示例 ```json { "error": { "code": "service_unavailable", "message": "Service under maintenance, please try again later" } } ``` ## 错误 HTTP 504 - POST /v1/audio/transcriptions ### 响应 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 } ``` ### 响应示例 ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "error": { "code": "timeout_error", "message": "The request timed out" } } ``` ## 生成的代码示例 直接使用 cURL，或安装所用语言的 SDK。每个示例都会提交本参考中经过验证的请求。 ### curl ```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"}' ``` ### javascript #### 安装 ```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" }); ``` ### python #### 安装 ```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" ) ``` ### go #### 安装 ```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 } ``` ### ruby #### 安装 ```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" ) ``` ### java #### 安装 ```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() ); } } ``` ### php #### 安装 ```bash composer require runapi-ai/openai-transcription ``` ```php speechToText->run([ "file" => "audio.mp3", "model" => "whisper-1", "response_format" => "json" ]); ``` ## 相关指南 - [API 身份验证](/docs/guides/authentication) - [快速开始](/docs/guides/task-api/quickstart)