Passo 1: Invia un file
Invia il tuo file in POST come multipart/form-data a /api/v1/convert con un parametro to_format che indica il formato di destinazione.
curl -X POST https://cleverutils.com/api/v1/convert \
-F "[email protected]" \
-F "to_format=jpg"
import requests
resp = requests.post(
"https://cleverutils.com/api/v1/convert",
files={"file": open("photo.heic", "rb")},
data={"to_format": "jpg"},
)
job = resp.json()["data"]
print(job["job_id"], job["output"]["url"])
import fs from "node:fs";
const form = new FormData();
form.append("file", new Blob([fs.readFileSync("photo.heic")]), "photo.heic");
form.append("to_format", "jpg");
const resp = await fetch("https://cleverutils.com/api/v1/convert", {
method: "POST",
body: form,
});
const { data: job } = await resp.json();
console.log(job.job_id, job.output.url);
<?php
$ch = curl_init("https://cleverutils.com/api/v1/convert");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => [
"file" => new CURLFile("photo.heic"),
"to_format" => "jpg",
],
]);
$resp = json_decode(curl_exec($ch), true);
$job = $resp["data"];
echo $job["job_id"], "\n", $job["output"]["url"];
package main
import (
"bytes"
"encoding/json"
"io"
"mime/multipart"
"net/http"
"os"
)
func main() {
body := &bytes.Buffer{}
w := multipart.NewWriter(body)
f, _ := os.Open("photo.heic")
fw, _ := w.CreateFormFile("file", "photo.heic")
io.Copy(fw, f)
w.WriteField("to_format", "jpg")
w.Close()
req, _ := http.NewRequest("POST", "https://cleverutils.com/api/v1/convert", body)
req.Header.Set("Content-Type", w.FormDataContentType())
resp, _ := http.DefaultClient.Do(req)
var out struct {
Data struct{ JobID string `json:"job_id"` } `json:"data"`
}
json.NewDecoder(resp.Body).Decode(&out)
println(out.Data.JobID)
}
require 'net/http'
require 'json'
uri = URI('https://cleverutils.com/api/v1/convert')
req = Net::HTTP::Post.new(uri)
req.set_form(
[
['file', File.open('photo.heic')],
['to_format', 'jpg']
],
'multipart/form-data'
)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
job = JSON.parse(res.body)['data']
puts job['job_id'], job['output']['url']
// Java 11+ HttpClient with multipart (using a small helper)
import java.net.URI;
import java.net.http.*;
import java.nio.file.*;
var boundary = "----CleverUtils" + System.currentTimeMillis();
var CRLF = "\r\n";
var file = Path.of("photo.heic");
var fileBytes = Files.readAllBytes(file);
var body = ("--" + boundary + CRLF
+ "Content-Disposition: form-data; name=\"to_format\"" + CRLF + CRLF + "jpg" + CRLF
+ "--" + boundary + CRLF
+ "Content-Disposition: form-data; name=\"file\"; filename=\"photo.heic\"" + CRLF
+ "Content-Type: application/octet-stream" + CRLF + CRLF).getBytes();
var tail = (CRLF + "--" + boundary + "--" + CRLF).getBytes();
var full = new byte[body.length + fileBytes.length + tail.length];
System.arraycopy(body, 0, full, 0, body.length);
System.arraycopy(fileBytes, 0, full, body.length, fileBytes.length);
System.arraycopy(tail, 0, full, body.length + fileBytes.length, tail.length);
var req = HttpRequest.newBuilder(URI.create("https://cleverutils.com/api/v1/convert"))
.header("Content-Type", "multipart/form-data; boundary=" + boundary)
.POST(HttpRequest.BodyPublishers.ofByteArray(full))
.build();
var res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text.Json;
using var client = new HttpClient();
using var form = new MultipartFormDataContent();
var fileContent = new ByteArrayContent(File.ReadAllBytes("photo.heic"));
fileContent.Headers.ContentType = MediaTypeHeaderValue.Parse("application/octet-stream");
form.Add(fileContent, "file", "photo.heic");
form.Add(new StringContent("jpg"), "to_format");
var response = await client.PostAsync("https://cleverutils.com/api/v1/convert", form);
var json = await response.Content.ReadAsStringAsync();
var doc = JsonDocument.Parse(json).RootElement.GetProperty("data");
Console.WriteLine(doc.GetProperty("job_id").GetString());
Passo 2: Leggi la risposta
L'API restituisce una busta JSON canonica con un job_id e link che puoi usare per interrogare lo stato e scaricare il risultato.
{
"data": {
"job_id": "5f8c1a2e9d4b7c0e3f6a8b2d1e4c5f78",
"status": "done",
"output": {
"filename": "photo_cleverutils.com.jpg",
"size_bytes": 184523,
"size_human": "180 KB",
"url": "https://cleverutils.com/api/v1/jobs/5f8c.../output"
},
"links": {
"self": "https://cleverutils.com/api/v1/jobs/5f8c...",
"output": "https://cleverutils.com/api/v1/jobs/5f8c.../output"
},
"expires_at": "2026-04-10T14:32:11Z"
}
}
Per i file piccoli, la conversione viene eseguita in modo sincrono e la risposta contiene già status: "done". Per i file più grandi otterrai status: "processing" e dovrai interrogare il job finché non è pronto.
Passo 3: Scarica il risultato
Usa l'URL di data.output.url per scaricare il file convertito. L'API trasmette il file come allegato binario.
curl -o photo.jpg https://cleverutils.com/api/v1/jobs/5f8c.../output
Polling per job asincroni
Se il tuo file è grande o la risposta mostra status: "processing", interroga l'endpoint del job ogni pochi secondi finché non è terminato.
import time, requests
while True:
s = requests.get(f"https://cleverutils.com/api/v1/jobs/{job_id}").json()["data"]
if s["status"] == "done":
break
if s["status"] == "error":
raise RuntimeError(s)
time.sleep(2)
out = requests.get(s["output"]["url"])
open("result.jpg", "wb").write(out.content)
Elaborazione in batch
Per convertire molti file in una volta, usa POST /api/v1/batch con fino a 20 file in un'unica richiesta.
curl -X POST https://cleverutils.com/api/v1/batch \
-F "files[][email protected]" \
-F "files[][email protected]" \
-F "files[][email protected]" \
-F "to_format=jpg"
Ogni file nel batch conta singolarmente sulla tua quota giornaliera (massimo 20 file per richiesta).
Cosa fare dopo?
- Riferimento completo degli endpoint — ogni endpoint, ogni parametro, ogni campo di risposta.
- Limiti di frequenza — quote, header e come non farsi limitare.
- Codici di errore — ogni errore che potresti vedere e come risolverlo.