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

# Create a file

> Register an MP3 or WAV file of up to 1.5 GB before uploading it. Next, get an upload URL, upload the bytes, and complete the upload. Retrying with the same operation_id and body returns the same file.

<section className="api-next-steps" aria-label="Continue building">
  ## Continue building

  <Columns cols={2}>
    <Card title="Arrange background audio" icon="book-open" href="/guides/studio-projects">Upload files and place them on tracks.</Card>
    <Card title="Create an instance" icon="audio-lines" href="/api-reference/studio/create-an-instance">Place a ready file on a track.</Card>
    <Card title="Studio CLI" icon="terminal" href="/cli/reference/studio">Run the same operations from a terminal.</Card>
  </Columns>
</section>


## OpenAPI

````yaml /openapi.json post /v1/studio/files
openapi: 3.1.0
info:
  title: Breeze Developer API
  description: >-
    Breeze Developer API for models, voices, text-to-speech, history, balance,
    usage, and browser-managed API keys.
  version: 1.0.0
servers:
  - url: https://api.breeze.blue
security: []
tags:
  - name: Models
    description: Supported TTS models.
  - name: Text to Speech
    description: Text-to-speech synthesis and instruction enhancement.
  - name: Voices
    description: Saved voices and voice settings.
  - name: Voice Previews
    description: Create, audition, and save temporary voice previews.
  - name: Account
    description: Balance, usage, and API keys.
  - name: History
    description: Generated audio history.
  - name: Studio
    description: Projects, scripts, arrangement and audio materials.
paths:
  /v1/studio/files:
    post:
      tags:
        - Studio
      summary: Create a file
      description: >-
        Register an MP3 or WAV file of up to 1.5 GB before uploading it. Next,
        get an upload URL, upload the bytes, and complete the upload. Retrying
        with the same operation_id and body returns the same file.
      operationId: studio_files_create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileCreate'
      responses:
        '200':
          description: The created file, with status uploading.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileView'
          headers:
            x-breeze-api-key-id:
              description: >-
                Public API key identifier used to authenticate the request, when
                an API key was used.
              schema:
                type: string
        '401':
          description: HTTP 401 error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: HTTP 404 error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: HTTP 409 error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: HTTP 422 error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '504':
          description: HTTP 504 error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |-
            curl \
              --request POST \
              --url "https://api.breeze.blue/v1/studio/files" \
              --header "xi-api-key: $BREEZE_API_KEY" \
              --header "Content-Type: application/json" \
              --data '{
              "operation_id": "123e4567-e89b-42d3-a456-426614174000",
              "project_id": "prj_example",
              "name": "background.mp3",
              "size_bytes": 5242880,
              "mime_type": "audio/mpeg"
            }'
        - lang: Python
          label: Python
          source: |-
            from breeze_blue import BreezeBlue

            client = BreezeBlue()
            result = client.studio.files.create({
                "operation_id": "123e4567-e89b-42d3-a456-426614174000",
                "project_id": "prj_example",
                "name": "background.mp3",
                "size_bytes": 5242880,
                "mime_type": "audio/mpeg",
            })
        - lang: TypeScript
          label: TypeScript
          source: |-
            import { BreezeBlueClient } from "@breeze.blue/sdk";

            const client = new BreezeBlueClient();
            const result = await client.studio.files.create({
              operationId: "123e4567-e89b-42d3-a456-426614174000",
              projectId: "prj_example",
              name: "background.mp3",
              sizeBytes: 5242880,
              mimeType: "audio/mpeg",
            });
components:
  schemas:
    FileCreate:
      properties:
        operation_id:
          type: string
          format: uuid
          title: Operation Id
          description: >-
            New UUID for each write. Retrying with the same ID and body returns
            the original result instead of repeating the write.
        project_id:
          anyOf:
            - type: string
              maxLength: 128
              minLength: 1
              pattern: \S
            - type: 'null'
          title: Project Id
          description: Project that owns the file. Omit for a personal file.
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
          description: File name, without path separators.
        size_bytes:
          type: integer
          maximum: 1610612736
          minimum: 1
          title: Size Bytes
          description: Exact upload size in bytes, up to 1.5 GB.
        mime_type:
          type: string
          enum:
            - audio/mpeg
            - audio/wav
          title: Mime Type
          description: audio/mpeg for MP3 or audio/wav for WAV.
      additionalProperties: false
      type: object
      required:
        - operation_id
        - name
        - size_bytes
        - mime_type
      title: FileCreate
    FileView:
      properties:
        id:
          type: string
          title: Id
          description: File ID.
        project_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Project Id
          description: Project that owns the file; null for a personal file.
        name:
          type: string
          title: Name
          description: File name.
        revision:
          type: integer
          title: Revision
          description: Current revision. Send it as expected_revision to rename or delete.
        status:
          type: string
          enum:
            - uploading
            - queued
            - running
            - ready
            - failed
          title: Status
          description: >-
            uploading until the upload is completed, then queued and running
            while processing, and finally ready or failed.
        frames:
          anyOf:
            - type: integer
            - type: 'null'
          title: Frames
          description: Length in frames at sample_rate, once processed.
        sample_rate:
          type: integer
          title: Sample Rate
          description: 'Frame rate used for all Studio timing: 48000.'
        size_bytes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Size Bytes
          description: Original upload size in bytes.
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
          description: Error code when processing failed.
        error_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Reason
          description: Machine-readable failure reason.
        error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Message
          description: Readable failure message.
        references:
          type: integer
          title: References
          description: Number of instances that use the file.
      additionalProperties: false
      type: object
      required:
        - id
        - project_id
        - name
        - revision
        - status
        - frames
        - sample_rate
        - size_bytes
        - error_code
        - error_reason
        - error_message
        - references
      title: FileView
    ErrorResponse:
      properties:
        ok:
          default: false
          title: Ok
          type: boolean
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        error:
          title: Error
          type: string
        meta:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          default: null
          title: Meta
      required:
        - code
        - detail
        - error
      title: ErrorResponse
      type: object
    ValidationErrorResponse:
      properties:
        ok:
          default: false
          title: Ok
          type: boolean
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        error:
          title: Error
          type: string
        meta:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Meta
      required:
        - code
        - detail
        - error
      title: ValidationErrorResponse
      type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: xi-api-key
      description: Breeze Developer API key.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.