ShareX and the API

An upload token lets a tool upload to your copium.pics account without you signing in. Manage yours on the ShareX & API page, which you can also reach from Account under Upload tokens & API access.

Treat your token like a password

Anyone with your token can use the API as you. They can upload, list, rename and delete your uploads, shorten links and change most settings. A token can't create or revoke tokens, download your data, delete your account or change how you sign in. Never post it in public. If it leaks, press Revoke on ShareX & API straight away: changing your password doesn't revoke tokens. Resetting your password with Forgot? revokes every token and disconnects every app.

Set up ShareX

ShareX is a free screenshot tool for Windows. With ShareX you press a hotkey, drag over part of your screen, and the link is on your clipboard, already uploaded.

Install ShareX

Install ShareX on your Windows PC.

Download your personal config

On a free account, first choose which link ShareX copies: Direct image link or Share page link. With Copium+ there is no choice: ShareX copies the direct link, or the share page while your custom embed is on. Then press Download Copium.sxcu.

Open the file

Open the downloaded file. ShareX adds copium.pics as an upload destination.

Take a screenshot

Press Ctrl Print Screen. The link is copied for you.

Your ShareX config shortens links too. In ShareX, choose Destinations → URL shortener → Custom URL shortener.

Tokens and API keys

Free accounts have one token. Downloading a new config creates a new token and the old one stops working. ShareX asks you first: "This creates a new token - your old ShareX config and any scripts using the old token will stop working. Continue?" Press New token to go ahead.
Copium+ accounts can have up to 10 named API keys. Under API keys the page shows how many you have, such as 3 / 10. Type a name in New API key (for example Laptop or Bot), and use Rename to change it later. Each Copium+ config download creates a new named key ("ShareX 2" and so on) that counts toward the 10.
To remove a key, press Revoke and confirm: "Revoke “your key name”? Anything using it stops uploading."

Apps you connect with a code have their own connection and don't use up your API keys.

A new token or key is shown once. Copy it right away.

Token management can only be done while signed in on the website. If a token is used for it, you see "Sign in on the website to do this". Downloading your data and deleting your account are also website-only; for the export a token gets "Sign in on the website to download your data".

Upload from your own tools

Send your token as a bearer token: Authorization: Bearer YOUR_TOKEN. Errors come back as JSON with an error message.

Upload

Send uploads to the upload address on the ShareX & API page (https://v.copium.pics/api/upload, or /user/api.php for the catbox API). Uploads sent through copium.pics itself can't be larger than 100 MB.

POST /api/upload, as a multipart form with the file in a field named file. It answers 201 with the upload's links:

url, the direct link
pageUrl, the share page
thumbUrl, the thumbnail
link, the one to copy (the share page if your custom embed is on, otherwise the direct file)
id and status

Optional fields: title, wait=1 (wait until processing is finished), watermark=0 (skip your Copium+ watermark) and url (shorten a link instead of uploading a file). You can also send JSON with a base64 data value, plus filename and title; JSON uploads can be up to 30 MB.

Uploads are processed in the background. GET /api/uploads/:id shows the status: pending, active, review or failed.

Other endpoints

Method and path	What it does
`GET /api/me`	Your account, plan, limits and usage
`GET /api/images`	List your uploads, 48 per page. Filter with `q`, `folder`, `tag`, `kind` (`image`, `video`, `audio`, `text`, `html` or `pdf`) and `cursor`
`PATCH /api/images/:id`	Change the title (`title`) or, with Copium+, the link name (`customName`)
`DELETE /api/images/:id`	Delete an upload
`POST /api/import`	Import files from links: send `urls` (up to 10) or a single `url`
`POST /api/paste`	Save text as a paste: send JSON with `content`, and optionally `title` and `language`
`POST /api/shorten`	Shorten a link with the form field `url` (30 a minute and 60 links an hour)

catbox-compatible API

POST /user/api.php works with tools that expect the catbox API. Send your token in the userhash field.

reqtype=fileupload with the file in fileToUpload.
reqtype=deletefiles with files set to file names such as id.ext, separated by spaces (up to 100).

Replies are plain text. Link uploads and albums aren't supported. Each IP address can make 120 requests every 10 minutes.

Discord webhook address

The Apps page can make a webhook-style address (Make a webhook URL) for tools that can post to a Discord webhook. Anyone with the address can use your account like any token holder. On a free account, making it replaces your ShareX token. Revoke it as "FiveM webhook" on ShareX & API.

Limits

100 uploads every 10 minutes per account.
File size, length and format limits are the same as on the website. See copium.pics and Video.

Error messages

You see	What it means
Please sign in	No token or session was sent
Upload token is invalid or was revoked	The token is wrong or was revoked
API token is invalid or was revoked	The same, from the catbox API
Sign in on the website to do this	That action can't use a token
This app connection can't do that	A connected app tried something it isn't allowed to do
Please accept the upload rules first	Accept the rules on the website once
Your account has been suspended	The account is suspended
No file received - send it in a form field named "file"	Add the `file` field
File is too big - images can be up to 200 MB	The file is over your limit
Only PNG, JPG, GIF and WEBP images are allowed	The file type isn't supported
You are uploading too fast - try again in a few minutes	Wait, then try again
Copium is short on space right now - try again in a few minutes	The server is short on space (HTTP 503 with `Retry-After: 60`). Wait, then try again
You have a lot of uploads still processing - try again in a minute	Too many of your uploads are waiting (HTTP 503 with `Retry-After: 60`). Wait, then try again
Copium could not save your upload right now - try again in a few minutes	A temporary problem (HTTP 503 with `Retry-After: 60`). Try again
That title isn't allowed	Choose a different title