> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Transcription

> Creates a task to process speech into readable text. Submit either an media file or a publicly accessible media URL.

## Converting Speech to Text with Precision

Our transcription service transforms spoken content into accurate, readable text, enabling you to make your media content searchable, accessible, and analytically valuable. This endpoint initiates a transcription task, processing your media file and returning a unique identifier that allows you to track and retrieve your results.

## Understanding Speech Transcription

Speech transcription technology analyzes media recordings of human speech or video that contains speech and converts them into written text. This process employs sophisticated machine learning models trained on diverse speech patterns, accents, and linguistic contexts to deliver high-quality text outputs. Our system handles various media formats and speaking situations, from clear studio recordings to more challenging environments with background noise.

When you submit an media file for transcription, our system:

1. Analyzes the audio signal to identify speech segments
2. Processes these segments through advanced recognition models
3. Applies language-specific rules and context awareness
4. Generates a readable text transcript that captures the spoken content

This transformation creates valuable text assets from your media content, enabling new ways to search, analyze, and repurpose your spoken material.

### Supported Languages

Our transcription service supports a wide range of languages. Some of the most commonly used include:

* English (`1`)
* Spanish (`54`)
* French (`76`)
* German (`31`)
* Mandarin Chinese (`139`)
* Japanese (`88`)
* Arabic (`4`)

<Card icon="languages" href="get-source-languages" arrow={true} cta="Go to Language Page">
  For a complete list of supported languages and their respective language codes, refer to our Language Support Documentation
</Card>

### Supported media Formats

For optimal transcription quality, we recommend using high-quality media with clear speech and minimal background noise. Our service accepts the following media formats:

* MP3 (`.mp3`)
* WAV (`.wav`)
* AAC (`.aac`)
* FLAC (`.flac`)
* MP4 (`.mp4`)
* MOV (`.mov`)
* MXF (`.mxf`)

<Info>
  Please note that MXF format support is exclusively available to customers on our Enterprise plan, offering professional broadcast-quality media handling for organizations with advanced needs.
</Info>

## Request Example

You can create a transcription task by either uploading an media file or providing a URL to an media resource. Here are examples using cURL::

* Using a local media file:

```bash [expandable] theme={null}
curl -X POST "https://client.camb.ai/apis/transcribe" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "language=1" \
  -F "media_file=@/path/to/your/media_file.mp3"
```

* Using a remote media URL:

```bash [expandable] theme={null}
curl -X POST "https://client.camb.ai/apis/transcribe" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "language=1" \
  -F "media_url=https://example.com/media_file.mp3"
```

Here's how to handle both scenarios in Python with the `requests` library:

```python [expandable] theme={null}
import requests

def create_transcription_task(api_key, language=1, media_file_path=None, media_url=None):
    """
    Initiates a transcription task using either an media file or URL.

    Args:
        api_key (str): API authentication key
        language (str): Language code (default: "en")
        media_file_path (str, optional): Path to local media file
        media_url (str, optional): URL of remote media resource

    Returns:
        dict: Response containing task_id for status tracking
    """
    url = "https://client.camb.ai/apis/transcribe"
    headers = {"x-api-key": api_key}
    data = {"language": language}
    files = None

    # Validate input
    if not (media_file_path or media_url):
        raise ValueError("Must provide either media_file_path or media_url")
        if media_file_path and media_url:
        raise ValueError("Provide only one of media_file_path or media_url")

    # Prepare request components
    if media_file_path:
        with open(media_file_path, "rb") as media_file:
            files = {"media_file": (media_file_path.split("/")[-1], media_file)}
    else:
        data["media_url"] = media_url

    # Execute request
    response = requests.post(url, headers=headers, files=files, data=data)

    if response.ok:
        return response.json()
    else:
        print(f"Error {response.status_code}: {response.text}")
        return None

# Example with file upload
file_result = create_transcription_task(
    api_key="your_api_key",
    media_file_path="meeting_recording.mp3",
    language=1 # English (United States)
)

# Example with media URL
url_result = create_transcription_task(
    api_key="your_api_key",
    media_url="https://storage.example.com/interview.mp3",
    language="54 # Spanish (Spain)
)
```

## Processing Time Considerations

Transcription processing time depends on several factors:

* **Media Duration**: Longer files naturally take more time to process
* **Media Quality**: Clear, high-quality recordings process more efficiently
* **Language Complexity**: Some languages may require more processing time
* **System Load**: Processing time can vary based on current system demand

## Next Steps: Monitoring Your Transcription Task

After submitting your transcription request, you'll want to monitor its progress and retrieve the results once processing completes. To do this:

1. Use the [`/transcribe/{task-id}`](poll-transcription-result) endpoint to check your task's status
2. Poll the status endpoint at reasonable intervals (we recommend 5-15 second intervals for most cases)
3. Once the status shows as `SUCCESS`, you can retrieve your full transcript

## Best Practices for Optimal Results

To get the most accurate transcriptions from our service:

1. **Use High-Quality Media**: Whenever possible, use media recorded in quiet environments with minimal background noise.

2. **Appropriate Media Format**: Submit uncompressed media formats like WAV or FLAC for best quality, or high-bitrate MP3s if file size is a concern.

3. **Speaker Clarity**: Encourage clear speaking with moderate pace for best recognition accuracy.

4. **Specify the Correct Language**: Always provide the correct language parameter to ensure our models apply the right language patterns.

5. **Segment Longer Content**: For very long recordings (over 2 hours), consider splitting into multiple smaller files for more efficient processing.

## Handling Common Issues

If you encounter problems with your transcription tasks, these troubleshooting steps may help:

### Rejected File Uploads

**Problem**: Your request returns an error about the file upload.

**Potential Solutions**:

* Verify your file is in one of our supported formats (`.mp3`, `.wav`, `.aac`, `.flac`, `.mp4`, `.mov`, `.mxf`)
* Check that your file isn't corrupted or empty
* Ensure your file doesn't exceed our size limit (20 MB)

### Incorrect Language Specification

**Problem**: Transcription results appear inaccurate or contain many errors.

**Potential Solutions**:

* Verify you specified the correct language code
* For multilingual content, choose the predominant language

## Taking Your Transcriptions Further

Once you've successfully transcribed your media content, consider these next steps:

1. **Semantic Analysis**: Extract key topics, sentiments, and entities from your transcribed text
2. **Content Indexing**: Make your media searchable by indexing the transcript content
3. **Accessibility Compliance**: Use transcripts to make your media content accessible to all users
4. **Translation**: Convert your transcript into other languages for global reach
5. **Summary Generation**: Create concise summaries of longer transcribed content


## OpenAPI

````yaml post /transcribe
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://client.camb.ai/apis
security: []
paths:
  /transcribe:
    post:
      tags:
        - Apis
      summary: Create Transcription
      operationId: transcribe_transcribe_post
      parameters: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_transcribe_transcribe_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskID'
                description: >-
                  A JSON that contains unique identifier for the task. This is
                  used to query the status of the transcription task that is
                  running. It is returned when a create request is made to
                  process speech into text.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    Body_transcribe_transcribe_post:
      allOf:
        - $ref: '#/components/schemas/CreateTaskWithNameAndDescription'
        - properties:
            language:
              $ref: '#/components/schemas/SourceLanguages'
            file:
              type: string
              format: binary
              title: Media File
              description: Media file for transcription
              deprecated: true
            media_file:
              type: string
              format: binary
              title: Media File
              description: Media file for transcription
            audio_url:
              type: string
              title: Audio URL
              description: >-
                Audio URL for transcription. (Supports both video and audio
                files)
              deprecated: true
            media_url:
              type: string
              title: Media URL
              description: >-
                Media URL for transcription. (Supports both video and audio
                files)
          type: object
          required:
            - language
      title: Body_transcribe_transcribe_post
    TaskID:
      properties:
        task_id:
          type: string
          title: Task ID
      type: object
      title: Task ID
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CreateTaskWithNameAndDescription:
      properties:
        project_name:
          type: string
          title: Project Name
          description: >-
            Enter a distinctive name for your project that reflects its purpose
            or content. This name will be displayed in your CAMB.AI workspace
            dashboard and used to organize related assets, transcriptions, etc..
            . Choose something memorable that helps you quickly identify this
            specific project among your other voice, audio and localization
            tasks.
          minLength: 3
          maxLength: 255
          nullable: true
        project_description:
          type: string
          title: Project Description
          description: >-
            Provide details about your project's goals and specifications.
            Include information such as the target languages for translation or
            dubbing, desired voice characteristics, emotional tones to capture,
            or specific audio processing requirements, outlining the workflow
            here can serve as valuable documentation for organizational
            purposes.
          minLength: 3
          maxLength: 5000
          nullable: true
    SourceLanguages:
      type: integer
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
        - 7
        - 8
        - 9
        - 10
        - 11
        - 12
        - 13
        - 14
        - 15
        - 16
        - 17
        - 18
        - 19
        - 20
        - 21
        - 22
        - 23
        - 24
        - 25
        - 26
        - 27
        - 28
        - 29
        - 30
        - 31
        - 32
        - 33
        - 34
        - 35
        - 36
        - 37
        - 38
        - 39
        - 40
        - 41
        - 42
        - 43
        - 44
        - 45
        - 46
        - 47
        - 48
        - 49
        - 50
        - 51
        - 52
        - 53
        - 54
        - 55
        - 56
        - 57
        - 58
        - 59
        - 60
        - 61
        - 62
        - 63
        - 64
        - 65
        - 66
        - 67
        - 68
        - 69
        - 70
        - 71
        - 73
        - 74
        - 75
        - 76
        - 78
        - 79
        - 80
        - 81
        - 82
        - 83
        - 84
        - 85
        - 86
        - 87
        - 88
        - 90
        - 91
        - 92
        - 93
        - 94
        - 95
        - 96
        - 97
        - 98
        - 99
        - 100
        - 101
        - 102
        - 103
        - 104
        - 106
        - 107
        - 108
        - 109
        - 110
        - 111
        - 112
        - 113
        - 114
        - 115
        - 116
        - 117
        - 118
        - 119
        - 120
        - 121
        - 122
        - 123
        - 124
        - 125
        - 126
        - 127
        - 128
        - 129
        - 130
        - 131
        - 132
        - 133
        - 134
        - 135
        - 136
        - 139
        - 140
        - 141
        - 142
        - 143
        - 144
        - 145
        - 146
        - 148
      default: 1
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        The `x-api-key` is a custom header required for authenticating requests
        to our API. Include this header in your request with the appropriate API
        key value to securely access our endpoints. You can find your API key(s)
        in the 'API' section of our studio website.

````