> ## Documentation Index > Fetch the complete documentation index at: https://docs.helve.dev/llms.txt > Use this file to discover all available pages before exploring further. # Transcribe a recording > Submits a prerecorded file by URL and returns a job immediately. Helve records the attempt before contacting the provider, retries rate limits, never re-sends an uncertain submission, and fails the job at its deadline rather than leaving it hanging. Poll `GET /v1/jobs/{id}` for the transcript. ## OpenAPI ````yaml openapi.json POST /v1/transcriptions openapi: 3.1.0 info: title: Helve API version: 1.0.0 description: >- One key, one request shape, one bill for the tools your software calls: web search across eleven engines, page extraction across nine, and transcription across three. Every response says which provider served it, how the request was adjusted for that provider, and what it cost. servers: - url: https://helve.dev description: Production security: - bearerAuth: [] tags: - name: Search description: >- Web search with one schema across Exa, Parallel, Tavily, Brave, Serper, Firecrawl, Linkup, Valyu, Jina, Octen, Perplexity, and the `fusion` panel. - name: Extract description: Fetch and clean pages by URL. - name: Transcription description: >- Durable speech-to-text jobs across AssemblyAI, Deepgram, and ElevenLabs. Submit a recording, poll the job. paths: /v1/transcriptions: post: tags: - Transcription summary: Transcribe a recording description: >- Submits a prerecorded file by URL and returns a job immediately. Helve records the attempt before contacting the provider, retries rate limits, never re-sends an uncertain submission, and fails the job at its deadline rather than leaving it hanging. Poll `GET /v1/jobs/{id}` for the transcript. operationId: createTranscription requestBody: required: true content: application/json: example: audio_url: https://example.com/recordings/standup.mp3 provider: auto diarize: true keyterms: - Helve - Stirrup schema: type: object properties: audio_url: type: string format: uri description: >- HTTPS URL of the recording, fetched by the provider. Signed URLs are fine; it must stay reachable until the provider has read it. No embedded credentials or fragments. provider: type: string enum: - assemblyai - deepgram - elevenlabs - auto description: >- Which speech-to-text provider runs the job. `auto` (default) picks the first configured provider. The choice is persisted on the job before execution. language: type: string pattern: ^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$ description: >- BCP-47-style language tag such as `en` or `en-US`. Omit to let the provider detect the language. diarize: type: boolean description: >- Label speakers in `words` as `speaker_0`, `speaker_1`, … in order of first appearance. Default false. keyterms: type: array items: type: string minItems: 1 description: >- Recognition hints: names, jargon, product terms. Supported on AssemblyAI, Deepgram Nova-3, and ElevenLabs Scribe v2; other models ignore them with a warning. timestamps: type: string enum: - word - none description: >- `word` (default) returns per-word timings in `result.words`; `none` omits them. strict: type: boolean description: >- When true, any option the selected provider or model cannot honour rejects the request instead of producing a warning. Default false. provider_options: type: object properties: assemblyai: type: object additionalProperties: nullable: true description: >- AssemblyAI-native options, for example `{ "model": "best" }`. deepgram: type: object additionalProperties: nullable: true description: >- Deepgram-native options, for example `{ "model": "nova-3" }`. elevenlabs: type: object additionalProperties: nullable: true description: >- ElevenLabs-native options, for example `{ "model_id": "scribe_v2" }`. additionalProperties: false description: >- Provider-native options, validated by the adapter. Model selection lives here. Transport settings such as URLs, callbacks, and authentication cannot be overridden. required: - audio_url additionalProperties: false responses: '202': description: Transcription accepted content: application/json: schema: type: object properties: id: type: string pattern: ^job_[0-9a-f-]{36}$ description: The job id, `job_…`. Poll `GET /v1/jobs/{id}` with it. tool: type: string enum: - transcription status: type: string enum: - queued - running - completed - failed description: >- `queued` and `running` are in progress; `completed` carries `result`; `failed` carries `error`. provider: type: string enum: - assemblyai - deepgram - elevenlabs description: The provider selected for this job, resolved from `auto`. model: type: string description: The provider model the job will run on. warnings: type: array items: type: object properties: code: type: string param: type: string message: type: string required: - code - message additionalProperties: false description: >- Options the selected provider or model cannot honour. Empty when the request was accepted exactly. created_at: type: string format: date-time required: - id - tool - status - provider - model - warnings - created_at additionalProperties: false '400': description: Invalid request content: application/json: schema: type: object properties: error: type: object properties: type: type: string enum: - unauthorized - invalid_request - provider_not_available - provider_not_configured - provider_error - not_found - insufficient_credits description: >- Stable machine-readable category. `invalid_request` carries validation issues in `detail`; `provider_error` carries the provider's own error body. message: type: string description: Human-readable explanation. detail: nullable: true description: >- Validation issues for `invalid_request`; the provider's error body for `provider_error`. required: - type - message additionalProperties: false required: - error additionalProperties: false '401': description: Missing or invalid API key content: application/json: schema: type: object properties: error: type: object properties: type: type: string enum: - unauthorized - invalid_request - provider_not_available - provider_not_configured - provider_error - not_found - insufficient_credits description: >- Stable machine-readable category. `invalid_request` carries validation issues in `detail`; `provider_error` carries the provider's own error body. message: type: string description: Human-readable explanation. detail: nullable: true description: >- Validation issues for `invalid_request`; the provider's error body for `provider_error`. required: - type - message additionalProperties: false required: - error additionalProperties: false '402': description: Insufficient credits content: application/json: schema: type: object properties: error: type: object properties: type: type: string enum: - unauthorized - invalid_request - provider_not_available - provider_not_configured - provider_error - not_found - insufficient_credits description: >- Stable machine-readable category. `invalid_request` carries validation issues in `detail`; `provider_error` carries the provider's own error body. message: type: string description: Human-readable explanation. detail: nullable: true description: >- Validation issues for `invalid_request`; the provider's error body for `provider_error`. required: - type - message additionalProperties: false required: - error additionalProperties: false '404': description: Job not found content: application/json: schema: type: object properties: error: type: object properties: type: type: string enum: - unauthorized - invalid_request - provider_not_available - provider_not_configured - provider_error - not_found - insufficient_credits description: >- Stable machine-readable category. `invalid_request` carries validation issues in `detail`; `provider_error` carries the provider's own error body. message: type: string description: Human-readable explanation. detail: nullable: true description: >- Validation issues for `invalid_request`; the provider's error body for `provider_error`. required: - type - message additionalProperties: false required: - error additionalProperties: false '503': description: Durable execution or provider unavailable content: application/json: schema: type: object properties: error: type: object properties: type: type: string enum: - unauthorized - invalid_request - provider_not_available - provider_not_configured - provider_error - not_found - insufficient_credits description: >- Stable machine-readable category. `invalid_request` carries validation issues in `detail`; `provider_error` carries the provider's own error body. message: type: string description: Human-readable explanation. detail: nullable: true description: >- Validation issues for `invalid_request`; the provider's error body for `provider_error`. required: - type - message additionalProperties: false required: - error additionalProperties: false security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key from the dashboard, `sk_live_…`, sent as `Authorization: Bearer sk_live_…`. ````