Pular para o conteúdo
Referência de API
Referência de API

Criar um Upload de File

Envie um arquivo local, uma URL HTTPS remota ou uma fonte em base64 e receba uma URL temporária.

Ver Markdown

Envie um arquivo local, uma URL HTTPS remota ou uma fonte em base64 e receba uma URL temporária.

Endpoint

POST /api/v1/files
URL base
https://runapi.ai
Versão da API
v1
Autenticação
Authorization: Bearer YOUR_API_KEY
02

Solicitação

Corpo JSON

Envie valores apenas no local de requisição listado.

application/json - Base64 source4 campos
file_namestring
Opcional

Nome de arquivo opcional para o File Upload criado.

sourceobject
Obrigatório

Bytes de origem codificados em Base64.

source.datastring
Obrigatório

Dados em Base64

source.typestring
Obrigatório

Seleciona a representação de origem em base64.

application/json - URL source4 campos
file_namestring
Opcional

Nome de arquivo opcional para o File Upload criado.

sourceobject
Obrigatório

Fonte HTTPS remota para download.

source.typestring
Obrigatório

Seleciona a representação de origem por URL.

source.urlstring
Obrigatório

URL HTTPS pública para download.

multipart/form-data2 campos
filestring
Obrigatório

Bytes do arquivo local a ser enviado.

file_namestring
Opcional

Nome de arquivo opcional para o File Upload criado.

03

Resposta de sucesso

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

Resposta de erro (401)

HTTP 401
Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

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

Resposta de erro (403)

HTTP 403
Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

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

Resposta de erro (400)

HTTP 400
Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

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

Resposta de erro (408)

HTTP 408
Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

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

Resposta de erro (413)

HTTP 413
Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

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

Resposta de erro (415)

HTTP 415
Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

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

Resposta de erro (422)

HTTP 422
Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

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

Resposta de erro (429)

HTTP 429
Esquema de resposta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensagem de erro legível por humanos.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Exemplo de resposta

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

Exemplo 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"}'