API reference

REST and MCP, one key.

Authentication

Create a key on Agents and send it as Authorization: Bearer sm_live_…. Keys act as you, with your plan’s limits. Revoke a key at any time.

curl -X POST https://supermedia.space/api/v1/ai/jobs \
  -H "Authorization: Bearer $SUPERMEDIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"capabilityId":"image.upscale.v1","imageUrl":"https://example.com/photo.jpg","wait":45}'

MCP server

Streamable HTTP at https://supermedia.space/api/mcp. Stateless; send your key in the Authorization header.

ToolWhat it does
list_capabilitiesWhat this server can do: API operations, AI tools with daily limits, and browser-only tools with links.
get_creditsFeature allowances, used, reserved, remaining, and monthly reset; legacy credits for existing purchases.
list_filesList files in the user's Drive, newest first, with storage usage.
get_fileFile details plus a download URL valid for 10 minutes.
import_fileDownload a public https URL (up to 100 MB) into the user's Drive.
delete_filePermanently delete a Drive file and its share link.
share_fileCreate a public link to a Drive file. Videos, images, audio, and PDFs play in the browser.
unshare_fileTurn off a file's public link.
edit_imageResize, compress, convert, crop to an aspect ratio, rotate, strip metadata, or watermark an image. The result is saved to Drive. Params by operation — resize: width, height, percent, fit (inside|cover|fill); compress: quality 1-100, format; convert: format (jpeg|png|webp); crop: aspectRatio like "9:16", position; rotate: degrees (90|180|270), flipHorizontal, flipVertical; watermark: text, position, sizePercent, opacityPercent.
upscale_imageAI super-resolution to about 2 megapixels (PiSA-SR). Counts toward the daily AI allowance.
remove_backgroundAI background removal; returns a transparent PNG (BiRefNet). Counts toward the daily AI allowance.
transcribe_mediaSpeech to text with timestamps from a Drive video/audio file or a public media URL. Check account usage for current duration and monthly allowances.
tiktok_transcriptTranscript with timestamps for a public TikTok video link.
get_jobState and result of an AI job.
save_result_to_driveKeep an AI image result in Drive (results otherwise expire after 24 hours).

REST

MethodPathDescription
GET/api/v1/capabilitiesEverything the API and agents can do. No key needed.
GET/api/v1/filesList Drive files and storage usage.
POST/api/v1/filesJSON {url, name?} imports a public URL (≤ 100 MB). Any other body is stored as the file (≤ 4 MB, ?name=).
GET/api/v1/files/{id}File details and a 10-minute download URL.
GET/api/v1/files/{id}/contentFile bytes (range requests supported).
POST/api/v1/files/{id}/sharePublic link. Body {expiresInDays?}.
DELETE/api/v1/files/{id}/shareTurn the link off.
DELETE/api/v1/files/{id}Delete permanently.
POST/api/v1/images/edit{fileId | imageUrl, operation, params} → new Drive file.
POST/api/v1/ai/jobs{capabilityId, fileId | imageUrl | url, wait?} starts an AI job.
GET/api/v1/ai/jobs/{id}?wait=30Job state and result.
POST/api/v1/ai/jobs/{id}/saveKeep an AI image result in Drive.

Limits and retention

API and MCP use the same feature allowances as the website and extensions. AI results are erased after 24 hours unless saved to Drive. Drive files stay until you delete them; Storage and file limits are listed on Pricing. Errors return { "error": "code", "correlationId" }. Social publishing and the video editor are coming soon.