Media

POST/api/v2/media

Upload media

Mastodon compatible User token Scope write

Body parameters

filefilerequired

descriptionstring

filter_namestring

filter_classstring

replace_idstring

Returns

curl -X POST "https://pixelfed.social/api/v2/media" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@pier.jpg" \
  -F "description=Wooden pier at sunset, two people fishing at the far end"

const form = new FormData();
form.append("file", fileInput.files[0]);
form.append("description", "Wooden pier at sunset, two people fishing at the far end");

const res = await fetch("https://pixelfed.social/api/v2/media", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: form,
});

const media = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v2/media",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    files={"file": open("pier.jpg", "rb")},
    data={
        "description": "Wooden pier at sunset, two people fishing at the far end",
    },
)

media = res.json()

use Illuminate\Support\Facades\Http;

$media = Http::acceptJson()
    ->withToken($token)
    ->attach('file', fopen('pier.jpg', 'r'), 'pier.jpg')
    ->post('https://pixelfed.social/api/v2/media', [
        'description' => 'Wooden pier at sunset, two people fishing at the far end',
    ])
    ->json();

Response

{
  "id": "728341067224219648",
  "type": "image",
  "url": null,
  "remote_url": null,
  "preview_url": "https://pixelfed.social/storage/m/_v2/2/pier.jpg?v=1757871611",
  "optimized_url": null,
  "text_url": null,
  "meta": null,
  "description": "Wooden pier at sunset, two people fishing at the far end",
  "license": null,
  "is_nsfw": false,
  "orientation": null,
  "filter_name": null,
  "filter_class": null,
  "mime": "image/jpeg",
  "blurhash": "U4Rfzst8?bt7ogayj[j[~pfQ9Goe%Mj[WBay"
}

{
  "message": "The file field must be a file of type: image/jpeg, image/jpg, image/png, image/gif.",
  "errors": {
    "file": ["The file field must be a file of type: image/jpeg, image/jpg, image/png, image/gif."]
  }
}

{
  "error": "Account size limit reached."
}

{
  "error": ""
}

POST/api/v1/media

Upload media (v1)

Mastodon compatible User token Scope write

Body parameters

filefilerequired

descriptionstring

filter_namestring

filter_classstring

Returns

curl -X POST "https://pixelfed.social/api/v1/media" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@pier.jpg" \
  -F "description=Wooden pier at sunset, two people fishing at the far end"

const form = new FormData();
form.append("file", fileInput.files[0]);
form.append("description", "Wooden pier at sunset, two people fishing at the far end");

const res = await fetch("https://pixelfed.social/api/v1/media", {
  method: "POST",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: form,
});

const media = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1/media",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    files={"file": open("pier.jpg", "rb")},
    data={
        "description": "Wooden pier at sunset, two people fishing at the far end",
    },
)

media = res.json()

use Illuminate\Support\Facades\Http;

$media = Http::acceptJson()
    ->withToken($token)
    ->attach('file', fopen('pier.jpg', 'r'), 'pier.jpg')
    ->post('https://pixelfed.social/api/v1/media', [
        'description' => 'Wooden pier at sunset, two people fishing at the far end',
    ])
    ->json();

Response

{
  "id": "728341067224219648",
  "type": "image",
  "url": "https://pixelfed.social/storage/m/_v2/2/pier.jpg?v=1757871611",
  "remote_url": null,
  "preview_url": "https://pixelfed.social/storage/m/_v2/2/pier.jpg?v=1757871611",
  "text_url": null,
  "meta": null,
  "description": "Wooden pier at sunset, two people fishing at the far end",
  "mime": "image/jpeg",
  "blurhash": "U4Rfzst8?bt7ogayj[j[~pfQ9Goe%Mj[WBay"
}

{
  "error": ""
}

GET/api/v1/media/{id}

Get an upload

Mastodon compatible User token Scope read

Path parameters

idstringrequired

Returns

curl "https://pixelfed.social/api/v1/media/728341067224219648" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

const res = await fetch("https://pixelfed.social/api/v1/media/728341067224219648", {
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
  },
});

const media = await res.json();

import requests

res = requests.get(
    "https://pixelfed.social/api/v1/media/728341067224219648",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
)

media = res.json()

use Illuminate\Support\Facades\Http;

$media = Http::acceptJson()
    ->withToken($token)
    ->get('https://pixelfed.social/api/v1/media/728341067224219648')
    ->json();

Response

{
  "id": "728341067224219648",
  "type": "image",
  "url": "https://pixelfed.social/storage/m/_v2/2/pier.jpg",
  "remote_url": null,
  "preview_url": "https://pixelfed.social/storage/m/_v2/2/pier_thumb.jpg",
  "text_url": null,
  "description": "Wooden pier at sunset, two people fishing at the far end",
  "mime": "image/jpeg",
  "blurhash": "UJF}Qo~W9aIV4.xuRjWB00WB-pof",
  "meta": {
    "focus": {
      "x": 0,
      "y": 0
    },
    "original": {
      "width": 1080,
      "height": 1350,
      "size": "1080x1350",
      "aspect": 0.8
    }
  }
}

{
  "id": "728341067224219648",
  "type": "image",
  "url": "https://pixelfed.social/storage/m/_v2/2/pier.jpg",
  "preview_url": "https://pixelfed.social/storage/m/_v2/2/pier_thumb.jpg",
  "description": "Wooden pier at sunset, two people fishing at the far end"
}

{
  "error": "Record not found"
}

PUT/api/v1/media/{id}

Update alt text

Mastodon compatible User token Scope write

Path parameters

idstringrequired

Body parameters

descriptionstring

Returns

curl -X PUT "https://pixelfed.social/api/v1/media/728341067224219648" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Wooden pier at sunset, two people fishing off the far end"
  }'

const res = await fetch("https://pixelfed.social/api/v1/media/728341067224219648", {
  method: "PUT",
  headers: {
    Accept: "application/json",
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    description: "Wooden pier at sunset, two people fishing off the far end",
  }),
});

const media = await res.json();

import requests

res = requests.put(
    "https://pixelfed.social/api/v1/media/728341067224219648",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    json={
        "description": "Wooden pier at sunset, two people fishing off the far end",
    },
)

media = res.json()

use Illuminate\Support\Facades\Http;

$media = Http::acceptJson()
    ->withToken($token)
    ->put('https://pixelfed.social/api/v1/media/728341067224219648', [
        'description' => 'Wooden pier at sunset, two people fishing off the far end',
    ])
    ->json();

Response

{
  "id": "728341067224219648",
  "type": "image",
  "url": "https://pixelfed.social/storage/m/_v2/2/pier.jpg",
  "preview_url": "https://pixelfed.social/storage/m/_v2/2/pier_thumb.jpg",
  "description": "Wooden pier at sunset, two people fishing off the far end",
  "mime": "image/jpeg",
  "blurhash": "UJF}Qo~W9aIV4.xuRjWB00WB-pof"
}

{
  "error": "Record not found"
}

{
  "error": "Too many attempts. Try again in a few minutes."
}

Pixelfed is free and open source software. Edit this page Report a docs issue