Skip to content

Importing Files

FreeConvert API supports many ways of importing files into our system, in order to get them processed.

Import File - From device

To upload a file from your device storage, use the import/upload API endpoint. This is a two-step process.

Request 1. Import Task creation

The first request returns a response containing details for uploading the file from your device. The response includes the URL to which the file must be uploaded, along with additional parameters that must be submitted with the file contents.

curl -X POST https://api.freeconvert.me/v1/process/import/upload \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

POST https://api.freeconvert.me/v1/process/import/upload HTTP/1.1
Host: api.freeconvert.me
Content-Type: application/json
Accept: application/json

const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: `Bearer ${access_token}`,
};

fetch("https://api.freeconvert.me/v1/process/import/upload", {
  method: "POST",
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

import requests

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer' + access_token
}

result = requests.post(
  'https://api.freeconvert.me/v1/process/import/upload',
  headers = headers
)

print(result.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer' + access_token
}

result = RestClient.post(
  'https://api.freeconvert.me/v1/process/import/upload',
  headers: headers
)

JSON.parse(result)

<?php

require 'vendor/autoload.php';

$headers = array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer ' $access_token,
);

$client = new \GuzzleHttp\Client();

try {
  $response = $client->request(
    'POST',
    'https://api.freeconvert.me/v1/process/import/upload',
    array(
      'headers' => $headers,
    )
  );
  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

// ...

URL obj = new URL("https://api.freeconvert.me/v1/process/import/upload");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");

int responseCode = con.getResponseCode();

BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream())
);

String inputLine;
StringBuffer response = new StringBuffer();

while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();

System.out.println(response.toString());

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": string{"application/json"},
    "Accept": string{"application/json"},
    "Authorization": string{"Bearer" + access_token},
  }

  req, err := http.NewRequest(
    "POST",
    "https://api.freeconvert.me/v1/process/import/upload"
  )
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
  // ...
}

Example response

{
    ...
    "result": {
        "form": {
            "url": "https://server100.freeconvert.me/api/upload/625e27e075ae740013481967",
            "parameters": {
                "signature": "503808ac1738adbd"
            }
        }
    },
    ...
}

Request 2. File upload

The second request uploads the file using the information returned from the first request.

# URL will be dynamic and will differ from task to task
curl -L "https://server100.freeconvert.me/api/upload/625e27e075ae740013481967/" \
  -F "signature=503808ac1738adbd" \
  -F "file=@/path/to/file.ext" \

# URL will be dynamic and will differ from task to task
POST https://server100.freeconvert.me/api/upload/625e27e075ae740013481967 HTTP/1.1
Host: server100.freeconvert.me
Content-Type: multipart/form-data;boundary="boundary"

# value1
--boundary
Content-Disposition: form-data; name="file"; filename="example.mp3"
Content-Type: audio/mpeg

# value2
--boundary
Content-Disposition: form-data; name="signature" signature_value

const formData = new FormData();

for (const parameter in task.result.form.parameters) {
  formData.append(parameter, task.result.form.parameters[parameter]);
}

formData.append("file" /*file stream or blob*/);

fetch(task.result.form.url, {
  method: "POST",
  body: formData,
  headers: {
    "Content-Type": "multipart/form-data",
  },
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

import requests

payload = {
  'signature': '9c5db43ce428c4c4'
}
files= [('file',(file_name ,open(file_path,'rb'),'audio/mpeg'))]

headers = {
  'Authorization': 'Bearer' + access_token
}

# URL will be dynamic and will differ from task to task
result = requests.request('POST', task.result.form.url, headers=headers, data=payload, files=files)

print(result.json())

require 'uri'
require 'net/http'
require 'json'

url = URI(task.result.form.url)

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)

request["Authorization"] = 'Bearer' + access_token

form_data = [
  ['file', File.open(file_path)],
  ['signature', '9c5db43ce428c4c4']
]

request.set_form form_data, 'multipart/form-data'

result = https.request(request)

JSON.parse(result)

<?php
$client = new Client();

$headers = [
  'Authorization' => 'Bearer ' $access_token
];

$options = [
  'multipart' => [
    [
      'name' => 'file',
      'contents' => Utils::tryFopen($file_path, 'r'),
      'filename' => $file_name,
      'headers'  => [
        'Content-Type' => '<Content-type header>'
      ]
    ],
    [
      'name' => 'signature',
      'contents' => '9c5db43ce428c4c4'
    ]
]];

try {
  $request = new Request(
    'POST',
    $task->result->form->url,
    $headers
  );

  $response = $client->sendAsync($request, $options)->wait();

  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

// ...

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post(task.result.form.url)
  .header("Authorization", String.format("Bearer %s", access_token))
  .field("file", new File(file_path))
  .field("signature", "9c5db43ce428c4c4")
  .asString();

package main

import (
  "fmt"
  "bytes"
  "mime/multipart"
  "os"
  "path/filepath"
  "io"
  "net/http"
  "io/ioutil"
)

func main() {
  url := task[result[form[url]]]
  method := "POST"

  payload := &bytes.Buffer{}
  writer := multipart.NewWriter(payload)
  file, errFile1 := os.Open(file_path)
  defer file.Close()

  part1, errFile1 := writer.CreateFormFile("file",filepath.Base(file_path))
  _, errFile1 = io.Copy(part1, file)

  if errFile1 != nil {
    fmt.Println(errFile1)
    return
  }
  _ = writer.WriteField("signature", "9c5db43ce428c4c4")
  err := writer.Close()

  if err != nil {
    fmt.Println(err)
    return
  }

  client := &http.Client {}
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }

  req.Header.Add("Authorization", "Bearer" + access_token)

  req.Header.Set("Content-Type", writer.FormDataContentType())
  res, err := client.Do(req)

  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

Please see API code examples for more examples of uploading files.

Import File - From URL

When importing a file directly from a URL, only one request is required. FreeConvert will automatically fetch the file from the URL specified in the url field.

curl -X POST https://api.freeconvert.me/v1/process/import/url \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

# Body Parameter
{
  "url": "https://example.com/some.jpg",
  "filename": "some.jpg", # optional
}

POST https://api.freeconvert.me/v1/process/import/url HTTP/1.1
Host: api.freeconvert.me
Content-Type: application/json
Accept: application/json

# Body Parameter
{
  "url": "https://example.com/some.jpg",
  "filename": "some.jpg", // optional
}

const inputBody = {
  url: "https://example.com/some.jpg",
  filename: "some.jpg", // optional
};
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: `Bearer ${access_token}`,
};

fetch("https://api.freeconvert.me/v1/process/import/url", {
  method: "POST",
  body: JSON.stringify(inputBody),
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

import requests

request_body = {
  'url': 'https://example.com/some.jpg',
  'filename': 'some.jpg', # optional
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer' + access_token
}

result = requests.post(
  'https://api.freeconvert.me/v1/process/import/url',
  data = request_body,
  headers = headers
)

print(result.json())

require 'rest-client'
require 'json'

request_body = {
  'url' => "https://example.com/some.jpg",
  'filename' => "some.jpg", # optional
}
headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer' + access_token
}

result = RestClient.post(
  'https://api.freeconvert.me/v1/process/import/url',
  body: request_body,
  headers: headers
)

JSON.parse(result)

<?php

require 'vendor/autoload.php';

$headers = array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer ' $access_token,
);

$client = new \GuzzleHttp\Client();

$request_body = array(
  'url' => "https://example.com/some.jpg",
  'filename' => "some.jpg", # optional
)

try {
  $response = $client->request(
    'POST',
    'https://api.freeconvert.me/v1/process/import/url',
    array(
      'headers' => $headers,
      'content' => json_encode($request_body),
    )
  );
  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

// ...

URL obj = new URL("https://api.freeconvert.me/v1/process/import/url");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");

int responseCode = con.getResponseCode();

BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream())
);

String inputLine;
StringBuffer response = new StringBuffer();

while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();

System.out.println(response.toString());

package main

import (
  "bytes"
  "net/http"
)

func main() {
  jsonReq := map[string][]string{
    "url": string{"https://example.com/some.jpg"},
    "filename": string{"some.jpg"}, // optional
  }
  headers := map[string][]string{
    "Content-Type": string{"application/json"},
    "Accept": string{"application/json"},
    "Authorization": string{"Bearer" + access_token},
  }

  data := bytes.NewBuffer([]byte{jsonReq})

  req, err := http.NewRequest(
    "POST",
    "https://api.freeconvert.me/v1/process/import/url",
    data
  )
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
  // ...
}

The FreeConvert API supports additional methods for importing files.