Skip to content
Lumean
POST/storage/url

Get File URL

Issues a temporary download link for a result file.

Pass the path exactly as it came in result.files[] or result.service_files[] of the order. The link in data.url lives about an hour and is fetched with a plain GET — no X-API-KEY needed. Expired link: just ask for a new one, the file itself lives until the order's retention limit.

Required key permission: orders.download.

Parameters

Values go straight into the request line, and the URL is built for you. Below are each parameter’s type, whether it is required, and its allowed values.

POSThttps://api.lumean.app/api/public/storage/url

    Request body

    application/jsonrequired

    Returns a temporary link (data.url, TTL about an hour). Fetch it with a plain GET — the X-API-KEY header is neither needed nor sent for the download itself.

    Result file
    {
      "path": "storage/42/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/result/output.mp3"
    }

    Fields

    pathrequired

    The full file path exactly as it arrived in the order's result.files[] or result.service_files[]. Do not assemble it by hand — it contains internal segments.

    string
    Example storage/42/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/result/output.mp3
    downloadoptional

    When true, the link is marked as an attachment: the file is saved under the human-readable order name instead of opening in a browser tab.

    default false
    boolean
    number_baseoptional

    Where chunk numbering starts in the file name: 1 → the first chunk is "001", 0 → "000". Defaults to 1.

    default 1
    Values01
    integer
    number_paddingoptional

    Width of the zero-padded chunk number, 1..4: 3 → "007". Defaults to 3. Keep it identical to the ZIP archive request, otherwise the same chunk is named differently on its own and inside the archive.

    default 31..4
    integer

    Possible responses

    200

    The temporary link is in data.url. It lives about an hour; fetch it with a plain GET, without X-API-KEY.

    Body example
    {
      "success": true,
      "message": "Download link generated.",
      "data": {
        "url": "https://s3.lumean.app/lumean/storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/final.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE1234567%2F20260717%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260717T150000Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c"
      }
    }
    Response fields
    successrequired

    Success flag. Branch on the HTTP status code instead: any 2xx response carries true here, while an error comes back in a different shape that need not contain this field at all.

    boolean
    messagerequired

    A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code.

    string
    datarequired

    The response payload.

    object
    urlrequired

    A temporary link to the file. Fetch it with a plain GET and no X-API-KEY header. It is short-lived — do not store it, request it right before downloading.

    string
    401

    The key is missing, unknown, disabled or expired.

    Analyse this response
    Body example
    {
      "success": false,
      "message": "API key is missing. Provide it in the X-API-KEY header.",
      "data": null
    }
    Response fields
    successrequired

    Always false in error responses.

    boolean
    messagerequired

    Error text in the key's language (set through the X-Locale header).

    string
    datarequired

    Always null when the request is rejected before processing.

    nullable
    null
    403

    The key lacks the required permission, or the object belongs to another user.

    Analyse this response
    Body example
    {
      "success": false,
      "message": "You do not have access to this file."
    }
    Response fields
    successrequired

    Always false in error responses.

    boolean
    messagerequired

    The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.

    string
    errorsrequired

    A per-field breakdown — present only on validation errors (422): the key names a request field, the value lists the complaints about it. Other codes send null, since there is nothing to break down and the whole reason is in message.

    nullable
    null
    404

    File not found: wrong path, or the order's retention period has passed.

    Analyse this response
    Body example
    {
      "success": false,
      "message": "File not found."
    }
    Response fields
    successrequired

    Always false in error responses.

    boolean
    messagerequired

    The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.

    string
    errorsrequired

    A per-field breakdown — present only on validation errors (422): the key names a request field, the value lists the complaints about it. Other codes send null, since there is nothing to break down and the whole reason is in message.

    nullable
    null
    422

    Validation error. Offending fields are listed in errors.

    Analyse this response
    Body example
    {
      "success": true,
      "message": "string",
      "errors": {}
    }
    Response fields
    successrequired

    Always false in error responses.

    boolean
    messagerequired

    A summary of the validation errors in words, in the response language (X-Locale).

    string
    errorsrequired

    A per-field breakdown: the key names a request field, the value lists the complaints about it.

    object
    *optional
    arbitrary keys
    array<string>
    500

    The link could not be issued. Retry — the operation is idempotent.

    Body example
    {
      "success": false,
      "message": "Failed to generate the download link. Please try again later."
    }
    Response fields
    successrequired

    Always false in error responses.

    boolean
    messagerequired

    The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.

    nullable
    null | array<any> | string | object
    errorsrequired

    A per-field breakdown — present only on validation errors (422): the key names a request field, the value lists the complaints about it. Other codes send null, since there is nothing to break down and the whole reason is in message.

    nullable
    null
    503

    The external provider is temporarily unavailable. Retry later.

    Body example
    {
      "success": false,
      "message": "Service temporarily unavailable."
    }
    Response fields
    successrequired

    Always false in error responses.

    boolean
    messagerequired

    The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.

    nullable
    null | array<any> | string | object

    This page for AI

    Open .mdllm.md

    API version 1.0.0