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

# Transcribe from URL

> Provide a remote audio or video URL for transcription. Synchronously-oriented endpoint that may return a completed result or pending status for longer jobs.

Submit a remote audio or video URL for transcription. Perfect for transcribing files hosted on cloud storage or social media platforms.

<Note>
  For file uploads instead, see [Transcribe from File](/api-reference/endpoint/create-from-file).
</Note>

## Supported URLs

You can transcribe audio from:

* Cloud storage (S3, Google Cloud Storage, Azure Blob)
* Social media platforms (YouTube, Twitter, etc.)
* Any publicly accessible audio/video URL


## OpenAPI

````yaml POST /v1/transcribe-url
openapi: 3.1.0
info:
  title: SkyScribe API
  version: 1.0.0
servers:
  - url: https://api.sky-scribe.com
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Transcribe
    description: Transcribe audio and video files to text
  - name: Translate
    description: Translate transcripts to different languages
  - name: Extract
    description: Extract structured data from transcripts
paths:
  /v1/transcribe-url:
    post:
      tags:
        - Transcribe
      summary: Transcribe from URL
      description: >-
        Provide a remote audio or video URL for transcription.
        Synchronously-oriented endpoint that may return a completed result or
        pending status for longer jobs.
      operationId: transcribeFromUrl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranscribeRequest'
            examples:
              url-transcription:
                summary: Transcribe from URL
                value:
                  audio_url: https://example.com/audio.mp3
                  language: en-US
                  format:
                    - json
                    - srt
                    - txt
                  diarize: true
              async-with-callback:
                summary: Async transcription with callback
                value:
                  audio_url: https://example.com/audio.mp3
                  callback: https://your-server.com/webhook
                  format:
                    - json
                    - pdf
                    - markdown
      responses:
        '200':
          description: >-
            Transcription response. Returns one of two response types:


            **Option 1 - Completed (status: "completed")**: Returned when no
            callback URL is provided (synchronous processing). Response includes
            status, id, and data with all requested formats (defaults to json if
            not specified).


            **Option 2 - Pending (status: "pending")**: Only returned when
            callback URL is provided (asynchronous processing). Response
            includes status, id, and poll_url to check progress. Results will be
            sent to the callback URL when complete.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/TranscriptionCompletedResponse'
                  - $ref: '#/components/schemas/PendingResponse'
        4XX:
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        5XX:
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    TranscribeRequest:
      type: object
      description: >-
        Transcription request. Must provide `audio_url` for URL-based
        transcription.
      properties:
        audio_url:
          type: string
          format: uri
          description: Remote audio/video URL (social media or cloud storage).
        language:
          type: string
          description: >-
            (Optional) Language hint (BCP-47 code, e.g., 'en-US', 'es-ES').
            Defaults to 'auto' for automatic detection.
        format:
          type: array
          description: >-
            (Optional) Output formats to generate. Available: doc, pdf, txt,
            markdown, srt, vtt, csv, json. Defaults to ["json"] if not provided.
          items:
            type: string
            enum:
              - doc
              - pdf
              - txt
              - markdown
              - srt
              - vtt
              - csv
              - json
            example: json
          default:
            - json
        callback:
          type: string
          format: uri
          description: >-
            (Optional) Webhook URL for async processing. If provided, the job
            runs asynchronously and results are sent to this URL when complete.
            Without callback, the endpoint processes synchronously.
        diarize:
          type: boolean
          description: >-
            (Optional) Enable speaker diarization to identify different
            speakers.
          default: false
        team_id:
          type: string
          description: >-
            (Optional) Team identifier. If not provided, uses your default
            workspace.
        folder_id:
          type: string
          description: >-
            (Optional) Folder identifier. If not provided, file will be added to
            the root of the workspace.
        output_config:
          $ref: '#/components/schemas/OutputConfig'
      required:
        - audio_url
    TranscriptionCompletedResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - completed
        id:
          type: string
        data:
          type: object
          description: >-
            Map of requested formats to their data. Only formats specified in
            the request will be present. If no formats were specified, defaults
            to json only.
          properties:
            json:
              type: object
              nullable: true
              properties:
                language:
                  type: string
                text:
                  type: string
                segments:
                  type: array
                  items:
                    $ref: '#/components/schemas/Segment'
              required:
                - language
                - text
            doc:
              type: object
              nullable: true
              properties:
                url:
                  type: string
                  format: uri
                  description: Download URL for the DOC file
            pdf:
              type: object
              nullable: true
              properties:
                url:
                  type: string
                  format: uri
                  description: Download URL for the PDF file
            txt:
              type: object
              nullable: true
              properties:
                url:
                  type: string
                  format: uri
                  description: Download URL for the TXT file
            markdown:
              type: string
              nullable: true
              description: Markdown formatted text content
            srt:
              type: object
              nullable: true
              properties:
                url:
                  type: string
                  format: uri
                  description: Download URL for the SRT file
            vtt:
              type: object
              nullable: true
              properties:
                url:
                  type: string
                  format: uri
                  description: Download URL for the VTT file
            csv:
              type: object
              nullable: true
              properties:
                url:
                  type: string
                  format: uri
                  description: Download URL for the CSV file
          additionalProperties: false
      required:
        - status
        - id
        - data
    PendingResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - pending
        id:
          type: string
        poll_url:
          type: string
          format: uri
          description: URL to poll for updated status or completed result.
        estimated_wait_seconds:
          type: integer
          format: int32
          nullable: true
      required:
        - status
        - id
        - poll_url
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            message:
              type: string
            code:
              type: string
              nullable: true
            param:
              type: string
              nullable: true
          required:
            - type
            - message
      required:
        - error
    OutputConfig:
      type: object
      description: (Optional) Configuration for output formatting.
      properties:
        include_timestamps:
          type: boolean
          description: (Optional) Include timestamp information in the JSON data.
          default: true
        include_speakers:
          type: boolean
          description: >-
            (Optional) Include speaker labels in the JSON data (requires
            diarization).
          default: false
    Segment:
      type: object
      properties:
        id:
          type: string
        start:
          type: number
          format: float
          description: Start time in seconds.
        end:
          type: number
          format: float
          description: End time in seconds.
        text:
          type: string
        speaker:
          type: string
          nullable: true
      required:
        - id
        - start
        - end
        - text
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````