跳到正文
RunAPI 开发者文档
EN 中文
API 参考
API 参考

OpenAI Transcription Speech-to-Text

提交同步Speech to Text请求，并在同一响应中接收结果。

查看 Markdown
01

概览

提交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
02

支持的模型

打开模型页可查看当前价格、限流和商业使用详情。

03

请求 Schema

JSON 请求体

只发送此端点声明的字段。

gpt-transcribe9 个字段
filestring
必填

Audio file upload, up to 25 MB.

keywordsarray
可选

Terms that should receive additional recognition guidance.

languagestring
可选

Audio language as an ISO-639-1 code.

languagesarray
可选

Candidate audio languages as ISO-639-1 codes.

modelstring
可选

Transcription model.

可选值: gpt-transcribe
promptstring
可选

Optional text that guides transcription style and vocabulary.

response_formatstring
可选

Response body format.

可选值: json, text
streamboolean
可选

Whether to request a streamed response when supported.

temperaturenumber
可选

Sampling temperature from 0 to 1.

范围: 0 - 1
whisper-18 个字段
filestring
必填

Audio file upload, up to 25 MB.

languagestring
可选

Audio language as an ISO-639-1 code.

modelstring
可选

Transcription model.

可选值: whisper-1
promptstring
可选

Optional text that guides transcription style and vocabulary.

response_formatstring
可选

Response body format.

可选值: json, text, srt, verbose_json, vtt
streamboolean
可选

Whether to request a streamed response when supported.

temperaturenumber
可选

Sampling temperature from 0 to 1.

范围: 0 - 1
timestamp_granularitiesarray
可选

Timestamp detail included with verbose JSON responses.

项数限制: 2
04

成功响应

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."
}
05

错误

HTTP 401

POST /v1/audio/transcriptions

此响应不包含正文。

06

错误

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"
  }
}
07

错误

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"
  }
}
08

错误

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"
  }
}
09

错误

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"
  }
}
10

错误

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."
  }
}
11

错误

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"
  }
}
12

错误

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"
  }
}
13

生成的代码示例

直接使用 cURL，或安装所用语言的 SDK。每个示例都会提交本参考中经过验证的请求。

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"}'

安装

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"
});

安装

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"
)

安装

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
}

安装

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"
)

安装

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()
    );
  }
}

安装

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"
]);
14

相关指南