Automate Uploads with an Image Hosting API

What an upload API changes

Uploading through a browser is fine at human scale: drag, drop, copy the link, done. It stops being fine the moment software enters the loop. A monitoring script that renders charts every night, a Discord bot that needs to attach images, a static site generator that publishes screenshots on deploy, a QA pipeline that captures failures, none of these can click a button. An upload API turns the host into a service your code calls directly: send a file with your key, get JSON back with every link you need, zero clicks anywhere in the chain. HotIMG keeps the endpoint deliberately small, one POST with two required fields, which means the two examples below are genuinely the whole integration. Everything after that is your own plumbing.

Get your key and guard it

Every request authenticates with a personal API key rather than a username and password. Create a free account, open your Dashboard and go to Settings, and your key is generated there, one per user, ready to copy into a script or a screenshot tool. Because the key is tied to your account, uploads made with it land in your library with your storage quota and your default settings, which is exactly what you want for automation. Treat the key like a password: anyone holding it can upload on your behalf and burn through your quota.

Your first upload with curl

The endpoint accepts standard multipart form data, so curl handles it in one command with no libraries involved:

curl -X POST "https://hotimg.com/api/1/upload" \
  -F "key=YOUR_API_KEY" \
  -F "[email protected]" \
  -F "name=sunset-pier" \
  -F "expiration=30d"

Reading it line by line: the -F flags build the multipart form, key authenticates you, and [email protected] attaches the local file. The optional name field sets a friendly filename for the upload, and expiration gives the image a lifetime, thirty days in this case. The image field is flexible about what you feed it: attach a file with the @ syntax as shown, pass a base64 encoded string of the file contents, or pass a plain URL and the server fetches the picture for you. That last form is quietly useful for migrating images between services without ever downloading them to your machine.

The same upload in Python

With the requests library, a production-ready version is about a dozen lines:

import os
import requests

API_KEY = os.environ["HOTIMG_API_KEY"]

with open("photo.jpg", "rb") as f:
    resp = requests.post(
        "https://hotimg.com/api/1/upload",
        data={"key": API_KEY, "name": "sunset-pier", "expiration": "never"},
        files={"image": f},
        timeout=60,
    )

resp.raise_for_status()
data = resp.json()["data"]
print(data["url"])         # direct link to the file
print(data["url_viewer"])  # viewer page for humans
print(data["thumb"])       # thumbnail for previews
print(data["delete_url"])  # keep this one private

Three details make this snippet safe to build on. The key comes from an environment variable instead of the source code. The timeout stops a stalled connection from hanging your job forever. And raise_for_status turns HTTP errors into exceptions you can catch and retry instead of silently parsing an error page. Wrap it in a function, point it at a folder, and you have a bulk uploader; add it to a cron job and your nightly charts publish themselves.

Every field the endpoint accepts

Expiration deserves a moment of thought before you pick a default. Temporary shares like error screenshots and debug captures can use 1h or 1d and clean up after themselves, which keeps your library free of one-time junk. Anything embedded somewhere permanent, a README badge, a blog image, a forum tutorial, should be never, because an expired image leaves a broken embed behind on a page you may not control. Registered HotIMG accounts include 25 GB of storage, so permanence costs you nothing until you are hosting a very large archive.

Reading the response

A successful upload returns JSON with a data object containing four links, each with a different job. data.url is the direct link to the raw file, the one you embed in HTML, Markdown or BBCode. data.url_viewer opens the image page with context, which is the better link to hand to a person. data.thumb is a small thumbnail, ideal for gallery grids and chat previews. data.delete_url removes the image when opened, so store it next to your upload record and keep it out of logs, tickets and anything public, because possession of that URL is the only credential deletion requires. If the split between the first two ever gets fuzzy, the comparison of direct links versus embed codes settles it in one line: software consumes direct links, people click viewer links.

Handle the unhappy path with the same care. When a request fails you get an error status and a message explaining why, and the causes are boringly consistent: a wrong or regenerated key, a file over the size limit, an unsupported format, or a malformed base64 string. Log the response body on failure rather than just the status code, because the message usually names the problem outright and saves you a debugging session. In scripts, also keep a small local manifest that maps each source file to its returned url and delete_url. It makes reruns skip work that already succeeded and gives you a way to clean up an entire batch later.

Automation recipes and good citizenship

The integrations people actually build are simpler than the word API suggests. A screenshot hotkey that uploads the capture and puts the direct link on your clipboard, laid out step by step in the screenshot workflow guide. A CI step that publishes visual artifacts like coverage charts or rendered previews. A bot that mirrors attachments into permanent storage. A one-off script that migrates a folder of legacy images off a dying host. Whatever you build, two habits keep it healthy. Shrink files before sending them, since smaller uploads run faster and respect your quota, and the guide to reducing image file size shows how to do it without visible loss. And file programmatic uploads into sets as you go with the albums and folders guide, because a script can create a mess considerably faster than a human. On the wire, be a good citizen: retry failures with exponential backoff instead of hammering the endpoint, check status codes rather than assuming success, and keep the API documentation bookmarked for response details and current limits.