본문으로 건너뛰기
API 레퍼런스
API 레퍼런스

File Upload 만들기

로컬 파일, 원격 HTTPS URL 또는 base64 소스 하나를 업로드하고 임시 URL을 받습니다.

Markdown 보기

로컬 파일, 원격 HTTPS URL 또는 base64 소스 하나를 업로드하고 임시 URL을 받습니다.

엔드포인트

POST /api/v1/files
Base URL
https://runapi.ai
API 버전
v1
인증
Authorization: Bearer YOUR_API_KEY
02

요청

JSON 본문

나열된 요청 위치에만 값을 전송하세요.

application/json - Base64 source필드 4개
file_namestring
선택

생성될 파일 업로드의 선택적 파일명.

sourceobject
필수

Base64로 인코딩된 소스 바이트.

source.datastring
필수

Base64 데이터

source.typestring
필수

base64 소스 표현 방식을 선택합니다.

application/json - URL source필드 4개
file_namestring
선택

생성될 파일 업로드의 선택적 파일명.

sourceobject
필수

다운로드할 원격 HTTPS 소스.

source.typestring
필수

URL 소스 표현 방식을 선택합니다.

source.urlstring
필수

다운로드할 공개 HTTPS URL.

multipart/form-data필드 2개
filestring
필수

업로드할 로컬 파일 바이트.

file_namestring
선택

생성될 파일 업로드의 선택적 파일명.

03

성공 응답

HTTP 201

POST /api/v1/files

JSON 
{
  "created_at": "2026-07-27T10:00:00.000Z",
  "expires_at": "2026-07-27T11:00:00.000Z",
  "file_name": "mask.png",
  "mime_type": "image/png",
  "size_bytes": 204800,
  "url": "https://file.runapi.ai/temp/user-uploads/mask.png"
}
04

오류 응답 (401)

HTTP 401
응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Authentication required"
}
05

오류 응답 (403)

HTTP 403
응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Standard API key required"
}
06

오류 응답 (400)

HTTP 400
응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Only HTTPS URLs are allowed"
}
07

오류 응답 (408)

HTTP 408
응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Download timeout"
}
08

오류 응답 (413)

HTTP 413
응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "File size exceeds the maximum allowed size"
}
09

오류 응답 (415)

HTTP 415
응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "This content type is not supported"
}
10

오류 응답 (422)

HTTP 422
응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "File upload failed. Please try again."
}
11

오류 응답 (429)

HTTP 429
응답 스키마
JSON 
{
  "properties": {
    "error": {
      "description": "사람이 읽을 수 있는 오류 메시지.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

응답 예시

JSON 
{
  "error": "Too many file uploads for this account. Please retry later."
}
12

cURL 예시

CURL 
curl -X POST https://runapi.ai/api/v1/files \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"source":{"type":"url","url":"https://cdn.runapi.ai/public/samples/mask.png"},"file_name":"mask.png"}'