Saltar al contenido
Referencia de API
Referencia de API

Crear un Upload de File

Sube un archivo local, una URL HTTPS remota o una fuente en base64 y recibe una URL temporal.

Ver Markdown

Sube un archivo local, una URL HTTPS remota o una fuente en base64 y recibe una URL temporal.

Endpoint

POST /api/v1/files
URL base
https://runapi.ai
Versión de la API
v1
Autenticación
Authorization: Bearer YOUR_API_KEY
02

Solicitud

Cuerpo JSON

Envíe valores únicamente en la ubicación de solicitud indicada.

application/json - Base64 source4 campos
file_namestring
Opcional

Nombre de archivo opcional para la Carga de Archivo creada.

sourceobject
Obligatorio

Bytes de origen codificados en Base64.

source.datastring
Obligatorio

Datos en Base64

source.typestring
Obligatorio

Selecciona la representación de fuente en base64.

application/json - URL source4 campos
file_namestring
Opcional

Nombre de archivo opcional para la Carga de Archivo creada.

sourceobject
Obligatorio

Origen HTTPS remoto para descargar.

source.typestring
Obligatorio

Selecciona la representación de fuente por URL.

source.urlstring
Obligatorio

URL pública HTTPS para descargar.

multipart/form-data2 campos
filestring
Obligatorio

Bytes del archivo local a cargar.

file_namestring
Opcional

Nombre de archivo opcional para la Carga de Archivo creada.

03

Respuesta de éxito

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

Respuesta de error (401)

HTTP 401
Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

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

Respuesta de error (403)

HTTP 403
Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

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

Respuesta de error (400)

HTTP 400
Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

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

Respuesta de error (408)

HTTP 408
Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

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

Respuesta de error (413)

HTTP 413
Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

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

Respuesta de error (415)

HTTP 415
Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

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

Respuesta de error (422)

HTTP 422
Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

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

Respuesta de error (429)

HTTP 429
Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

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

Ejemplo de 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"}'