openapi: 3.2.0
info:
  title: Ludo Ai Files API
  version: 0.9.10
  x-logo:
    url: /static/logo-small.png
    altText: Logo
  x-refined-note:
  - x-model-lineup differs across the merged source definitions and was not carried
  description: 'Operations tagged Files across 2 of this provider''s published API definitions: ludo-ai-rest-api-openapi.yml, ludo-ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: /api
tags:
- name: Files
paths:
  /assets/uploads:
    post:
      description: Start an upload of a local file, so it can be passed to a generation endpoint by URL instead of inline as base64. Declare the file's MIME type and exact size in bytes (up to 15MB, the same limit the generation endpoints apply); the response carries an upload_url and a file_url. Send the file's bytes in a single PUT to upload_url (no Authorization header; the content type and size are fixed by this call, and a body of any other size is refused). Once the PUT succeeds, pass file_url in any image, audio, video or model field that accepts a URL. The file is public to anyone holding file_url and is deleted 7 days after upload. upload_url is single-use. Free (no credits). Requires an API key (user scope). Not exposed as an MCP tool.
      tags:
      - Files
      operationId: createUpload
      x-mcp-exclude: true
      security:
      - ApiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUploadPayload'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSession'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -X POST \"https://api.ludo.ai/api/assets/uploads\" \\\n  -H \"Authorization: ApiKey YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"mime_type\":\"image/png\",\"size\":1}'"
      - lang: JavaScript
        label: JavaScript
        source: "const response = await fetch(\"https://api.ludo.ai/api/assets/uploads\", {\n  method: \"POST\",\n  headers: {\n    \"Authorization\": \"ApiKey YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"mime_type\": \"image/png\",\n    \"size\": 1\n  })\n});\n\nconst data = await response.json();\nconsole.log(data);"
      - lang: Python
        label: Python
        source: "import requests\n\nresponse = requests.post(\n    \"https://api.ludo.ai/api/assets/uploads\",\n    headers={\n        \"Authorization\": \"ApiKey YOUR_API_KEY\",\n        \"Content-Type\": \"application/json\"\n    },\n    json={\n      \"mime_type\": \"image/png\",\n      \"size\": 1\n    }\n)\n\nprint(response.json())"
      summary: Create upload
      x-summary-source: derived
    servers:
    - url: /api
components:
  schemas:
    CreateUploadPayload:
      type: object
      description: Payload for starting a file upload.
      required:
      - mime_type
      - size
      properties:
        mime_type:
          type: string
          description: MIME type of the file. Fixed for the upload; the stored file is served with it.
          enum:
          - image/png
          - image/jpeg
          - image/webp
          - image/gif
          - audio/mpeg
          - audio/wav
          - audio/x-wav
          - audio/ogg
          - audio/flac
          - audio/mp4
          - audio/aac
          - audio/webm
          - video/mp4
          - video/webm
          - video/quicktime
          - model/gltf-binary
          example: image/png
        size:
          type: integer
          format: int64
          minimum: 1
          maximum: 15728640
          description: Exact size of the file in bytes (at most 15MB). The PUT to upload_url must send exactly this many bytes.
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
        metadata:
          type: string
        error_payload:
          type: string
        intent:
          type: object
          description: Stripe intent details sent with 3D Secure (406) errors
          properties:
            id:
              type: string
            type:
              type: string
              enum:
              - payment
              - setup
              example: payment
            client_secret:
              type: string
    UploadSession:
      type: object
      required:
      - upload_url
      - file_url
      - mime_type
      - size
      properties:
        upload_url:
          type: string
          description: Single-use URL to PUT the file's bytes to, with no Authorization header.
          example: <url>
        file_url:
          type: string
          description: Public URL of the file once the PUT succeeds. Pass it to any field that accepts a URL. Deleted 7 days after upload.
          example: <url>
        mime_type:
          type: string
          description: The MIME type the file is stored and served with.
        size:
          type: integer
          format: int64
          description: The exact number of bytes the PUT must send.
  securitySchemes:
    ApiKey:
      type: apiKey
      name: Authorization
      in: header
      description: 'For accessing the API a valid API Key token must be passed in all the queries in

        the ''Authorization'' header.

        The following syntax must be used in the ''Authorization'' header: ApiKey xxxxxx.yyyyyyy.zzzzzz

        '
x-refined-from:
- ludo-ai-rest-api-openapi.yml
- ludo-ai-openapi.json