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

# 通过 URL 上传

> 获取有效期 24 小时的公开媒体 URL。

## 输入

使用 Bearer API Key。upload 为 multipart/form-data，其他方式为 JSON；uploadPath 是相对逻辑路径，fileName 可选。存储按账户隔离并使用独立对象版本，之后同名上传不会改掉旧任务使用的文件。

文件流/URL 上传上限 500 MiB。URL 拉取 30 秒超时，建议不超过 100 MiB；本站 Base64 解码文件上限 10 MiB，较大文件请使用 URL 或文件流。模型输入限制单独校验。

```json theme={null}
{
  "fileUrl": "https://example.com/sample.wav",
  "uploadPath": "audio",
  "fileName": "sample.wav"
}
```

## 输出

```json theme={null}
{
  "success": true,
  "code": 200,
  "msg": "File uploaded successfully",
  "data": {
    "fileName": "sample.wav",
    "filePath": "audio/sample.wav",
    "downloadUrl": "https://files.apistable.ai/uploads/account/version/sample.wav",
    "fileSize": 245760,
    "mimeType": "audio/wav",
    "uploadedAt": "2026-11-01T00:00:00Z",
    "expiresAt": "2026-11-02T00:00:00Z"
  }
}
```


## OpenAPI

````yaml openapi.json POST /api/v1/files/upload_url
openapi: 3.1.0
info:
  title: APIstable API
  version: 1.0.0-preview
  description: >-
    Public /api/v1 protocol. Valid API keys have the same account-scoped access.
    Read the selected model documentation for its ID, supported inputs, result
    format and availability before submitting. No client submission idempotency
    or max_credits. Availability, pricing, file retention and callback formats
    follow the selected model contract. Unconfigured operations return 503.
servers:
  - url: https://apistable.ai
    description: APIstable API
security: []
paths:
  /api/v1/files/upload_url:
    post:
      summary: 'Upload media: upload_url'
      description: >-
        Uploaded files expire after 24 hours. Account-scoped immutable object
        versions. Stream/URL maximum 500 MiB; Base64 decoded maximum 10 MiB.
      operationId: file_upload_url
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - fileUrl
              additionalProperties: false
              properties:
                fileUrl:
                  type: string
                uploadPath:
                  type: string
                  default: files
                fileName:
                  type: string
      responses:
        '200':
          description: Uploaded
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - code
                  - msg
                  - data
                properties:
                  success:
                    const: true
                  code:
                    const: 200
                  msg:
                    type: string
                  data:
                    type: object
                    required:
                      - fileName
                      - filePath
                      - downloadUrl
                      - fileSize
                      - mimeType
                      - uploadedAt
                      - expiresAt
                    properties:
                      fileName:
                        type: string
                      filePath:
                        type: string
                      downloadUrl:
                        type: string
                        format: uri
                      fileSize:
                        type: integer
                      mimeType:
                        type: string
                      uploadedAt:
                        type: string
                        format: date-time
                      expiresAt:
                        type: string
                        format: date-time
        '401':
          description: '40101: Invalid API key.'
        '503':
          description: Operation or provider unavailable
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Every valid key can submit and query its own account. Revoked keys are
        rejected.

````

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