PiAPI
HomeWorkspace
HomeWorkspace
Join Discord
  1. Tools
  • Get Started
    • Overview
    • Quickstart
    • Make Instruction: How to Use PiAPI to Build a Workflow on Make?
  • Endpoints
    • Song(Udio)
      • Song API Task Creation Examples
      • [Udio] Song Extend
      • Get Task
      • Create Task
      • [Udio] Generate Lyrics
    • Kling
      • Lipsync With PiAPI Kling API Examples
      • Motion Brush With PiAPI Kling API Example
      • Kling Elements Video Generation API
      • Kling Effects Video Generation
      • Cancel Task
        • Cancel Tasks
        • Cancel Task
      • Get Task
      • Create Task
      • Kling Virtual Try-On
    • Hailuo
      • Hailuo Director Mode Example
      • Generate Video
      • Get Task
    • Flux
      • Flux with LoRA and Controlnet
      • Available LoRA and Controlnet
      • Flux API with Redux Variation, Fill, Inpaint and Outpaint
      • Create Task
        • Text to Image
        • Image to Image
      • Get task
    • AI Hug
      • Get Task
      • Create Task
    • LLM
      • Use Cases for GPT-4o Image API
      • How To Avoid Timeouts in Completion API
      • GPT-4o Image Generation API
      • LLM API | Basic Completions
      • Get Task
    • Midjourney
      • PiAPI Penalties on Midjourney Usage
      • Detailed Explaination on Midjourney Task Result
      • Midjourney V7 API Instructions
      • Create Task
        • Imagine
        • Upscale
        • Variation
        • Reroll
        • Describe
        • Seed
        • Blend
        • Inpaint
        • Outpaint
        • Pan
      • Cancel Task
        • Cancel Task
        • Cancel Tasks
      • Get Task
    • Faceswap
      • Multi Faceswap
      • Image Faceswap
      • Video Faceswap
      • Get Task
    • TTS
      • Zeroshot Text-to-Speech F5-TTS
      • Get Task
    • Trellis
      • Create Task
      • Get Task
    • Luma Dream Machine
      • Cancel Task
        • Cancel Tasks
        • Cancel Task
      • Create Task
      • Get Task
    • WanX
      • Available LoRA Types for Wanx
      • Generate WanX Task with LoRA Using PiAPI
      • Use Cases for Wanx LoRA
      • Create Task
      • Get Task
    • Skyreels
      • Create Task
      • Get Task
    • Framepack
      • Create Task
      • Get Task
    • Hunyuan Video
      • How to Make a Hunyuan API Call
      • Get Task
      • Generate Video
    • Mmaudio
      • Get Task
      • Generate Audio
    • DiffRhythm
      • Generate Audio
      • Get Task
    • Tools
      • File Upload API
      • Video Upscale
        POST
      • Video Upscale-Get Task
        GET
      • Remove Background API
        POST
      • Remove Background-Get Task
        GET
      • Segment With Prompt API
        POST
      • Segment With Prompt API-Get Task
        GET
      • Image Upscale(Super Resolution) API
        POST
      • Image Upscale-Get Task
        GET
    • PiAPI Account Management
      • PiAPI Account Info
      • Task List Info
      • User Task History
  • Resources
    • Change Log
    • Output Storage
    • Unified API Schema
    • Webhook
    • Bulk Generation Service
    • Billings
    • PiAPI MCP Server
    • Workspace Manual
      • Host-your-account (HYA) | Back-up Account
      • Host-your-account (HYA) | Debug Checklist
      • Host-your-account (HYA) | Connected Account Status
    • Announcements
      • PiAPI 2025 January 1st Pricing Update
  • Legacy Documentation
    • Midjourney
      • Midjourney Webhook
      • Imagine
      • Reroll
      • Upscale
      • Variation
      • Inpaint
      • Outpaint
      • Pan
      • Describe
      • Blend
      • Seed
      • Fetch
      • Multi Fetch
      • Cancel
    • Face Swap
      • Video Faceswap
      • Multi-face-swap
      • Fetch
    • Dream Machine
      • Video Generation
      • Video Extend
      • Get Video Generation
    • Kling
      • Video Generation
      • Video Extend
      • Get Video Generation
  1. Tools

File Upload API

Ephemeral Resource Upload API#

Overview#

This API allows you to upload temporary files that will be automatically deleted after 24 hours. This API is Free of charge for Creator/Pro Plan. If you are on Free plan, you can not use it.

Base URL#

https://upload.theapi.app

Authentication#

Authentication is required via API key
Must be on the Creator plan or higher
Add your API key to the request headers as x-api-key

Endpoint: Upload Temporary File#

Upload a file that will be automatically deleted after 24 hours.

HTTP Request#

POST /api/ephemeral_resource

Headers#

HeaderValueDescription
Content-Typeapplication/jsonRequest body format
x-api-keyYOUR_API_KEYYour API authentication key

Request Body Parameters#

ParameterTypeRequiredDescription
file_namestringYesName of the file with extension (max 128 characters)
file_datastringYesBase64 encoded file data. Can include data URI if it matches the file's content type (max 10MB)

Supported File Extensions#

The following file extensions are supported (case-insensitive):
1.
jpg
2.
jpeg
3.
png
4.
webp
5.
mp4
6.
wav
7.
mp3

File Name Requirements#

Must not be empty
Must include one of the supported extensions
Maximum length: 128 characters
Extensions are case-insensitive

File Data Requirements#

Must be provided as a base64 string
Maximum size: 10MB
Optional data URI is supported
If data URI is included, its content-type must match the file extension's content-type

Example Request#

Success Response#

A successful request will return a 200 status code with the following response structure:
{
  "code": 200,
  "data": {
    "url": "https://example.com/example.png"
  },
  "message": "success"
}

Error Responses#

Invalid Request (400)#

Returned when the request parameters are invalid (e.g., unsupported file type, file too large).
{
  "code": 400,
  "message": "Invalid request parameters"
}

Insufficient Permissions (403)#

Returned when the user's plan level is insufficient (requires Creator plan or higher).
{
  "code": 403,
  "message": "Insufficient plan level"
}

Important Notes#

1.
Uploaded files are automatically deleted after 24 hours
2.
The service requires a Creator plan or higher
3.
The file_data field can include a data URI, but if included, its content-type must match the file extension's expected content-type
4.
File names are validated for supported extensions in a case-insensitive manner

Additional Examples#

Example with JPG file#

Example with MP3 file#

Modified at 2025-01-17 13:01:34
Previous
Get Task
Next
Video Upscale