SnapiX API Ref­er­ences

Con­cepts and Notes

• New: Now we have a SDK!
• New: See the MCP Serv­er doc­u­men­ta­tion for AI/LLM in­te­gra­tion via the Mod­el Con­text Pro­to­col.

App cred­its

1 App cred­it al­low you to make 1 op­er­a­tion, like pro­cess­ing an im­age via our API. So, for ex­am­ple, if you have a com­plex re­quest where you want to:

• Con­vert the im­age to 3 dif­fer­ent for­mats and re­size it in one res­o­lu­tion: will cost you 3 cred­its. In this count if you up­load­ing im­ages via the web in­ter­face to a cus­tom buck­et you will be charged 1 App cred­it per im­age for­mat.
• Re­size the im­age in 3 dif­fer­ent res­o­lu­tions and one for­mat: will cost you 3 cred­its.
• Con­vert the im­age to 3 dif­fer­ent for­mats and re­size it in 3 dif­fer­ent res­o­lu­tions: will cost you (3x3) 9 cred­its.
• Con­vert the an im­age on fly via our con­vert API you will be charged 1 App cred­it.

Out­put For­mat Com­pres­sion and Op­tions

SnapiX, ac­cord­ing­ly its API, is based on the High per­for­mance Node.js im­age pro­cess­ing li­brary Sharp. The out­put for­mats are lim­it­ed to PNG, JPEG, WEBP and AVIF. The com­pres­sion lev­el for the dif­fer­ent for­mats is pre­de­fined by the ap­pli­ca­tion and can­not be changed. Cur­rent­ly via the API we sup­port all re­size im­ages.

Icons (.ico files)

Un­like the Web in­ter­face we do not sup­port gen­er­at­ing (con­vert to) .ico files via the API. This is be­cause the this op­er­a­tion is re­al­ly rare used. We may sup­port it in the fu­ture in case there is enough de­mand.

Im­age Pro­cess­ing and Up­load API

Re­quire­ments

You must pro­vide an ac­tive API key, have suf­fi­cient App cred­its to per­form the op­er­a­tion, and enough stor­age space to up­load the im­age.

API_KEY="sk_snapix_apiKey-a1b2c3-placeholder"

API Key Per­mis­sions

API keys use a gran­u­lar per­mis­sions mod­el. Each key holds an ar­ray of per­mis­sions that con­trol which end­points it can ac­cess. The de­fault when cre­at­ing a key is ["images-read", "galleries-read"] (read-only ac­cess).

You can con­fig­ure per­mis­sions when cre­at­ing a key on the API Keys page, and up­date them at any time.

Im­ages per­mis­sions:

Gal­leries per­mis­sions:

Ex­am­ples:

• Read-only key: ["images-read", "galleries-read"]
• Full-ac­cess key: all 11 per­mis­sions above
• Up­load-only key: ["images-create"]

Any re­quest that re­quires a per­mis­sion not present in the key re­turns 403 Forbidden.

Up­load Im­ages (POST)

Up­loads an im­age (pro­vid­ed as form data file/URL field) to the ob­ject stor­age, per­forms ini­tial pro­cess­ing based on pro­vid­ed op­tions, and re­turns a JSON re­sponse. The im­age could be pro­vid­ed as bi­na­ry data or as a URL.

The re­sponse in­cludes de­tails about the up­loaded im­age, any gen­er­at­ed vari­ants, the base URL for ac­cess­ing these vari­ants, and their cor­re­spond­ing ob­ject keys (file­names). The ac­tu­al URL of an im­age vari­ant is ${urlBase}/${objectKey} and it can be ex­tract­ed from the JSON re­sponse.

Up­load im­age and con­vert it with the de­fault set­tings

Up­load the im­age and con­vert it to the de­fault out­put for­mat AVIF, keep the orig­i­nal as­pect ra­tio and res­o­lu­tion. Op­tion­al­ly in the ex­am­ples is used the com­mand jq to pret­ty for­mat the JSON re­sponse.

curl -X POST \
  "https://www.snapix.space/api/v1/images" \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "contentType=image/png" \
  -F "name=test-1.png" \
  -F "description=Test image description" \
  -F "image=@./test-1.png" | jq

• Use the image field to up­load the im­age as a bi­na­ry file.
• We high­ly rec­om­mend to ex­plic­it­ly set the contentType field, oth­er­wise the process may fail in un­pre­dictable ways. If you do not spec­i­fy "contentType=" we will try to parse it with fall­back to application/octet-stream.
• The @ sym­bol tells curl to read the file from the giv­en path (ab­solute or rel­a­tive).
• The ex­plic­it contentType set is not manda­to­ry, we will try to parse the con­tent type from the file. But if we can't, the API will throw an er­ror.
• The ex­plic­it name set is not manda­to­ry, we will try to parse the name from the file. But if we can't, the API will throw an er­ror. The max length is 256 char­ac­ters. In the re­sponse the name is the prop­er­ty named originalName.
• The ex­plic­it description set is not manda­to­ry. The max length is 4096 char­ac­ters.
• This re­quest will con­sume 1 App cred­it.

Up­load im­age and add it to one or more gal­leries

You can pro­vide an ar­ray of gallery Id(s) in the galleries field, thus the im­age will be added to the spec­i­fied gal­leries.

curl -X POST \
  "https://www.snapix.space/api/v1/images" \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "contentType=image/png" \
  -F "name=test-1.png" \
  -F 'galleries=["7618c305...", "bedee85f..."]' \
  -F "image=@./test-1.png" | jq

• The galleries field must be a valid JSON ar­ray of strings, which match­es ac­tu­al Ids of the gal­leries you want to add the im­age to.

Get im­age from URL and con­vert it with the de­fault set­tings

Get im­age from URL and con­vert it to the de­fault out­put for­mat AVIF, keep the orig­i­nal as­pect ra­tio and res­o­lu­tion.

curl -X POST \
  "https://www.snapix.space/api/v1/images" \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "url=https://images.snapix.space/abc-123/def-456.png" | jq

• Use the url field to up­load the im­age from a URL. All oth­er fields are op­tion­al, but avail­able for use.
• Note the image field take prece­dence over the url field, you you must use only one of them.
• This re­quest will con­sume 1 App cred­it.

Up­load and con­vert im­age to mul­ti­ple out­put for­mats and res­o­lu­tions

In this ex­am­ple we up­load the im­age and con­vert it to mul­ti­ple out­put res­o­lu­tions. By pass­ing an ar­ray of op­tions ob­jects to the resizeOptions field, we can spec­i­fy mul­ti­ple out­put res­o­lu­tions. By pass­ing an ar­ray of out­put for­mats to the formats field, we can spec­i­fy mul­ti­ple out­put for­mats.

curl -X POST \
  "https://www.snapix.space/api/v1/images" \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "contentType=image/webp" \
  -F "image=@./test-1.webp" \
  -F "name=test-1.webp" \
  -F "description=Test image description" \
  -F "ratio=1.777" \
  -F 'formatOptions=[{"format": "webp"}, {"format": "avif"}]' \
  -F 'resizeOptions=[{}, {"width": 720}, {"height": 580}]' | jq

• This re­quest will con­sume 6 App cred­its (2 for formatOptions * 3 for resizeOptions).

• The ratio field must be a valid num­ber. For ex­am­ple 16:9 ra­tio is 1.777, 4:3 ra­tio is 1.333. If not pro­vid­ed, the orig­i­nal one will be kept with the oth­er op­er­a­tions (i.e. re­size).

• The resizeOptions field must be a valid JSON ar­ray. If an emp­ty ob­ject is passed in the ar­ray, the im­age will be processed us­ing the de­fault op­tions, re­tain­ing its orig­i­nal res­o­lu­tion, etc.

  • On the back­end, we use the ex­cel­lent Sharp li­brary for im­age pro­cess­ing. Any valid op­tions from the Sharp re­size doc­u­men­ta­tion can be ap­plied. For ref­er­ence, see the Re­sizeOp­tions type on GitHub.
  • In ad­di­tion to the de­fault Sharp's op­tions, we also sup­port the fol­low­ing op­tions:
    • "padding": { "px": number, "py": number }: Add padding to the im­age.

• The formatOptions field must be a valid JSON ar­ray of ob­jects like:

  [
    {
      "format": "jpeg", // "jpeg" | "png" | "webp" | "avif",
      "options": {
        "background": "#FF0000", // Hex color
        "quality": 70, // 80 is default, recommended range: 60-85
        "mozjpeg": true, // Use mozjpeg encoder for JPEG images
        "chromaSubsampling": "4:2:0", // Most efficient color sampling
        "progressive": true, // Use progressive JPEG
        "force": true // Force output format
        // More options...
      }
    }
  ]
  

  • If you skip the formatOptions field or pass an emp­ty ar­ray, the im­age will be processed us­ing the de­fault op­tions, and will be out­put in the de­fault out­put for­mat for the API, which is webp.

  • The format prop­er­ty is re­quired and, the valid out­put for­mats for our API are: ["png", "jpeg", "webp", "avif"]

  • The options ob­ject is op­tion­al. If you skip the options, the im­age will be processed us­ing the de­fault op­tions.

    Re­fer to the Sharp doc­u­men­ta­tion for valid val­ues per for­mat:
    png, jpeg, webp and avif

    In ad­di­tion to these prop­er­ties, you can pro­vide a background val­ue as a hex col­or. This is use­ful when con­vert­ing trans­par­ent im­ages to a sol­id back­ground (e.g., con­vert­ing to jpeg). The de­fault back­ground col­or is #FFFFFF.

    You can pass background also to the resizeOptions field, it will be used as back­ground of the un­filled ar­eas when when you re­size with contain and oth­er sim­i­lar cas­es.

    curl -X POST \
      "https://www.snapix.space/api/v1/images" \
      -H "Authorization: Bearer ${API_KEY}" \
      -F "contentType=image/webp" \
      -F "image=@./test-1.webp" \
      -F "name=test-1.webp" \
      -F "ratio=1.777" \
      -F 'formatOptions=[{"format": "webp", "options": {"background": "#FF0"}}]' \
      -F 'resizeOptions=[{"width": 720}, {"height": 580}]' | jq
    

  • De­spite of the formatOptions pro­vid­ed the thumb­nails (for the fron­tend) will be out­put with op­tions like:

    {
     format: webp,
     options: { quality: 30 }
    }
    

Re­sponse

• The ac­tu­al URL of a im­age vari­ant is ${urlBase}/${objectKey}.

{
  "data": [
    {
      "id": "b27c40a1-1b80-4cd7-8a5a-43a7be53806c",
      "urlBase": "https://www.snapix.space/2t7YzLFAGr...",
      // Base URL for the uploaded images
      "originalName": "test-2.webp",
      "description": "Test image description",
      "metadata": [
        {
          "size": 39477,
          "idSuffix": 1024,
          "imageInfo": {
            "type": "avif",
            "ratio": 1,
            "width": 1024,
            "height": 1024
          },
          "objectKey": "b27c40a1-1b80-4cd7-8a5a-43a7be53806c-1024x1024.avif",
          // The image name in the user's account object storage
          "contentType": "image/avif",
          "lastModified": 1746103095199,
          "fileExtension": "avif",
          "optimizationPercent": 83
        },
        {
          "size": 3348,
          "idSuffix": "thumb_small",
          ...
          // App required resolution, the users are not charged for this,
          // but can use it for free
        },
        {
          "size": 12032,
          "idSuffix": "thumb_big",
          ...
          // App required resolution, the users are not charged for this,
          // but can use it for free
        },
        {
          "size": 237234,
          "idSuffix": "original",
          "objectKey": null,
          ...
          // System information for the original image,
          // NOTE: We do not store the original image!
        }
      ],
      "size": 39477,
      // The size in bytes that user's account storage will be charged
      "createdAt": "2025-05-01T12:38:14.070Z",
      "updatedAt": "2025-05-01T12:38:15.526Z"
      "galleries": [
        // If the image was uploaded to one or more galleries, otherwise empty []
        {
          "galleryId": "bedee85f-efcb-40ed-b571-180750fa3e98",
          "imageId": "935cc219-5ea6-44cd-b2b6-9fcaad1174e2"
        },
        ...
      ]

    }
    ...
    // More objects if you've requested more resizeOptions
  ],
  "simpleData": [
    {
      "id": "b27c40a1-1b80-4cd7-8a5a-43a7be53806c",
      "originalName": "test-2.webp",
      "variants": {
        "avif": "https:https://www.snapix.space/2t7YzLFAGr.../b27...6c-1024x1024.avif",
        // "jpeg", "png", "webp" -- If they are requested by the formatOptions
      },
      "info": {
        "width": 1024,
        "height": 1024,
        "ratio": 1
      }
    },
    ...
    // More objects if you've requested more resizeOptions
  ],
  "accountStatistics": {
    "storageUsed": 39477, // Current used user's storage in bytes
    "totalStorage": 188743680, // Total user's storage in bytes
    "creditsUsed": 1, // Credits used for this request
    "remainingCredits": 49, // Remaining credits of the account
    "remainingCreditsPaidPlans": 0 // Remaining credits from paid plans
  }
}

Ex­am­ple how to ex­tract im­age(s) URLs from the re­sponse

Here is ex­tend­ed jq com­mand to ex­tract the URLs of the up­loaded im­age vari­ants.

JQ_FILTER='.images[] | .urlBase as $baseUrl | .metadata[] | select(.objectKey != null) | "\($baseUrl)/\(.objectKey)"'
curl -X POST... | jq -r "$JQ_FILTER"

Sec­ond ap­proach to ex­tract the URLs, by us­ing extract_urls func­tion.

extract_urls() { jq -r '.images[] | .urlBase as $baseUrl | .metadata[] | select(.objectKey != null) | "\($baseUrl)/\(.objectKey)"' }
curl -X POST... | extract_urls

Get Im­age List Pag­i­nat­ed (GET)

This API is de­signed for pag­i­nat­ed re­trieval of user im­ages, per buck­et. You are not charged for this op­er­a­tion. The user's API call rate lim­its are ap­plied.

Re­quest

The de­fault query pa­ra­me­ters are:

• page=1 - page num­ber,
• limit=50 - max­i­mum num­ber of im­ages per page, the max. al­low­able val­ue is 200,
• sort=asc - asc (as­cend­ing - new­er to old­er) or desc (de­scend­ing - old­er to new­er),
• bucketKey=snapix_default_bucket - for more de­tails check the Cus­tom Buck­ets sec­tion be­low.

curl -X GET "https://www.snapix.space/api/v1/images" \
  -H "Authorization: Bearer ${API_KEY}" | jq

curl -X GET "https://www.snapix.space/api/v1/images?bucketKey=snapix_default_bucket&page=1&limit=10&sort=asc" \
  -H "Authorization: Bearer ${API_KEY}" | jq

• The re­quest does not cost any App cred­its.

Re­sponse

{
  "data": [
    {
      "id": "b27c40a1-1b80-4cd7-8a5a-43a7be53806c",
      "urlBase": "https://www.snapix.space/2t7YzLFAGr...",
      // Base URL for the uploaded images
      "originalName": "test-2.webp",
      "description": "Test image description",
      "metadata": [
        {
          "size": 39477,
          "idSuffix": 1024,
          "imageInfo": {
            "type": "avif",
            "ratio": 1,
            "width": 1024,
            "height": 1024
          },
          "objectKey": "b27c40a1-1b80-4cd7-8a5a-43a7be53806c-1024.avif",
          // The image name in the user's account object storage
          "contentType": "image/avif",
          "lastModified": 1746103095199,
          "fileExtension": "avif",
          "optimizationPercent": 83
        },
        {
          "size": 3348,
          "idSuffix": "thumb_small",
          ...
          // App required resolution, the users are not charged for this,
          // but can use it for free
        },
        {
          "size": 12032,
          "idSuffix": "thumb_big",
          ...
          // App required resolution, the users are not charged for this,
          // but can use it for free
        },
        {
          "size": 237234,
          "idSuffix": "original",
          "objectKey": null,
          ...
          // System information for the original image,
          // NOTE: We do not store the original image!
        }
      ],
      "size": 39477,
      // The size in bytes that user's account storage will be charged
      "createdAt": "2025-05-01T12:38:14.070Z",
      "updatedAt": "2025-05-01T12:38:15.526Z"
    }
    ...
  ],
  "simpleData":
  [
    {
      "id": "b27c40a1-1b80-4cd7-8a5a-43a7be53806c",
      "originalName": "test-2.webp",
      "variants": {
        "avif": "https:https://www.snapix.space/2t7YzLFAGr.../b27...6c-1024x1024.avif",
      },
      "info": {
        "width": 1024,
        "height": 1024,
        "ratio": 1
      }
    },
    ...
  ],
  "accountStatistics": {
    "storageUsed": 509477, // Current used user's storage in bytes
    "totalStorage": 188743680, // Total user's storage in bytes
    "creditsUsed": 0, // Credits used for this request
    "remainingCredits": 109, // Remaining credits of the account
    "remainingCreditsPaidPlans": 0 // Remaining credits from paid plans
  }
  "pagination": {
    "page": 1,
    "limit": 2,
    "total": 3,
    "totalPages": 2,
    "hasNext": true,
    "hasPrevious": false,
    "nextPage": 2,
    "previousPage": null
  }
}

Get an Im­age (GET)

This API is de­signed for re­triev­ing a sin­gle im­age - by Id. You are not charged for this op­er­a­tion. The user's API call rate lim­its are ap­plied.

Re­quest

curl -X GET "https://www.snapix.space/api/v1/images/${ID}" \
  -H "Authorization: Bearer ${API_KEY}" | jq

• The re­quest does not cost any App cred­its.

Re­sponse

{
  "data": {
    "id": "8602d021-30bb-4deb-ae9f-21e981463a94",
    "urlBase": "https://www.snapix.space/2t7YzLFAGr...",
    "bucketKey": "snapix_default_bucket",
    "originalName": "Image-55",
    "description": "Test image description",
    "metadata": [
      {
        "idSuffix": "thumb_small",
        ...
      },
      {
        "idSuffix": "thumb_big",
        ...
      },
      {
        "idSuffix": "original",
        ...
      },
      {
        "size": 61514,
        "idSuffix": "1024x576",
        "imageInfo": {
          "type": "webp",
          "ratio": 1.78,
          "width": 1024,
          "height": 576
        },
        "objectKey": "8602d021-3...a94-1024x576.webp",
        "contentType": "image/webp",
        "lastModified": 1757438708663,
        "fileExtension": "webp",
        "optimizationPercent": 85
      }
    ],
    "size": 61514,
    "createdAt": "2025-09-09T17:25:08.565Z",
    "updatedAt": "2025-09-09T17:25:08.894Z",
    "galleries": [
      {
        "galleryId": "7618c305-37b9-4a06-b986-9c62b285875c",
        "imageId": "8602d021-30bb-4deb-ae9f-21e981463a94"
      },
      {
        "galleryId": "bedee85f-efcb-40ed-b571-180750fa3e98",
        "imageId": "8602d021-30bb-4deb-ae9f-21e981463a94"
      }
    ]
  },
  "simpleData": {
    "id": "8602d021-30bb-4deb-ae9f-21e981463a94",
    "originalName": "Image-55",
    "variants": {
      "webp": "https://www.snapix.space/2t.../860...x576.webp"
    },
    "info": {
      "width": 1024,
      "height": 576,
      "ratio": 1.78
    }
  }
}

Up­date an Im­age (PATCH/PUT)

This API is de­signed for up­dat­ing a sin­gle im­age - by Id. You are charged for this op­er­a­tion only if it re­quires im­age pro­cess­ing - i.e. when you up­date only the name or the de­scrip­tion you will not be charged. The user's API call rate lim­its are ap­plied.

Ac­tu­al­ly we ex­pose the same func­tion for PUT /api/v1/images/${ID} and PATCH /api/v1/images/${ID} re­quests, so the both can be used in­ter­change­ably and they be­haves in the PATCH re­quest way.

Re­quest

curl -X PATCH \
  "https://www.snapix.space/api/v1/images/${ID}" \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "contentType=image/webp" \
  -F "image=@./test-117.webp" \
  -F "name=New name" \
  -F "description=This is an updated description" \
  -F "ratio=1.777" \
  -F 'galleries=["bedee85f..."]' \
  -F "storageKeyHandling=unique" \
  -F 'formatOptions=[{"format": "webp"}, {"format": "avif"}]' \
  -F 'resizeOptions={"width": 720}' | jq

• This re­quest will con­sume 2 App cred­its (for the formatOptions ar­ray).

• The op­tions are iden­ti­cal to the Up­load and con­vert im­age to mul­ti­ple out­put for­mats and res­o­lu­tions ex­am­ple.

  • The only dif­fer­ence is that here we pass resizeOptions as an ob­ject in­stead of an ar­ray.
  • And of course the end­point.

• You must pro­vide at least one of the fol­low­ing fields: image (or url), name, description, or galleries; oth­er­wise, there will be no data to process.

• storageKeyHandling de­ter­mines how ob­ject keys are man­aged. Op­tions:

  • replace (de­fault) - reuse the ex­ist­ing key. You don’t need to ex­plic­it­ly pro­vide this val­ue;
  • unique - ap­pend a ran­dom suf­fix to gen­er­ate a new key (en­sures im­me­di­ate CDN up­dates but re­quires your app to han­dle the new name).

• If you want to just re­size an ex­ist­ing im­age you can pro­vide it via the url field.

  curl -X PATCH \
    "https://www.snapix.space/api/v1/images/${ID}" \
    -H "Authorization: Bearer ${API_KEY}" \
    -F "url=https://images.snapix.space/2t7../img..-1080.webp" \
    -F 'resizeOptions={"width": 720}' | jq
  

• If you pro­vide the galleries field, the im­age will be added to the spec­i­fied gal­leries and re­moved from any gal­leries not in­clud­ed in the list. If you omit the galleries field, the im­age’s gallery as­so­ci­a­tions will re­main un­changed. To re­move the im­age from all gal­leries, pass an emp­ty ar­ray: galleries = []:

  curl -X PATCH \
    "https://www.snapix.space/api/v1/images/${ID}" \
    -H "Authorization: Bearer ${API_KEY}" \
    -F "galleries=[]" | jq
  

Re­sponse

{
  "data": {
    "id": "f948f86a-c79d-4649-bf09-5cd6d55526b9",
    "urlBase": "https://www.snapix.space/2t7YzLFAGr...",
    "bucketKey": "snapix_default_bucket",
    "originalName": "New name",
    "description": "Updated description",
    "metadata": [
      {
        "size": 876,
        "idSuffix": "thumb_small",
        "imageInfo": {
          "type": "webp",
          "ratio": 1.76,
          "width": 120,
          "height": 68
        },
        "objectKey": "f4...9a-blank-thumb_small.webp",
        "contentType": "image/webp",
        "lastModified": 1758546579928,
        "fileExtension": "webp",
        "optimizationPercent": 99
      },
      {
        "size": 4116,
        "idSuffix": "thumb_big",
        "imageInfo": {
          "type": "webp",
          "ratio": 1.78,
          "width": 320,
          "height": 180
        },
        "objectKey": "f4...9a-pheasant-thumb_big.webp",
        "contentType": "image/webp",
        "lastModified": 1758546579936,
        "fileExtension": "webp",
        "optimizationPercent": 94
      },
      {
        "size": 26622,
        "idSuffix": "720x405",
        "imageInfo": {
          "type": "webp",
          "ratio": 1.78,
          "width": 720,
          "height": 405
        },
        "objectKey": "f4...9a-teal-720x405.webp",
        "contentType": "image/webp",
        "lastModified": 1758546579962,
        "fileExtension": "webp",
        "optimizationPercent": 60
      },
      {
        "size": 20152,
        "idSuffix": "720x405",
        "imageInfo": {
          "type": "avif",
          "ratio": 1.78,
          "width": 720,
          "height": 405
        },
        "objectKey": "f4...9a-silver-720x405.avif",
        "contentType": "image/avif",
        "lastModified": 1758546580884,
        "fileExtension": "avif",
        "optimizationPercent": 70
      },
      {
        "size": 66452,
        "idSuffix": "original",
        "imageInfo": {
          "type": "jpg",
          "ratio": 1.9,
          "width": 1200,
          "height": 630
        },
        "objectKey": null,
        "contentType": "image/webp",
        "lastModified": 1758546579246,
        "fileExtension": "jpg",
        "optimizationPercent": 0
      }
    ],
    "size": 46774,
    "createdAt": "2025-09-03T11:48:37.660Z",
    "updatedAt": "2025-09-22T13:09:41.485Z",
    "galleries": [
      {
        "galleryId": "bedee85f-efcb-40ed-b571-180750fa3e98",
        "imageId": "f4...9a"
      }
    ]
  },
  "simpleData": {
    "id": "f4...9a",
    "originalName": "New name",
    "variants": {
      "webp": "https://www.snapix.space/2t7YzLFAGr.../f4...9a-teal-720x405.webp",
      "avif": "https://www.snapix.space/2t7YzLFAGr.../f4...9a-silver-720x405.avif"
    },
    "info": {
      "width": 720,
      "height": 405,
      "ratio": 1.78
    }
  },
  "accountStatistics": {
    "storageUsed": 165384,
    "totalStorage": 5242880,
    "creditsUsed": 2,
    "remainingCredits": 340,
    "remainingCreditsPaidPlans": 60
  }
}

Delete Im­age (DELETE)

This API is de­signed for delet­ing a sin­gle im­age - by Id.

Re­quest

curl -X DELETE "https://www.snapix.space/api/v1/images/${ID}" \
  -H "Authorization: Bearer ${API_KEY}" | jq

Re­sponse

null

Cus­tom Buck­ets

By de­fault, all im­ages are up­loaded to the default buck­et of {{ ap­pli­ca­tion­Name }}. You can see its de­tails in the Buck­ets page.

Reg­is­tered users can cre­ate and man­age cus­tom buck­ets from the Buck­ets page.

• You can des­ig­nate one buck­et as the primary buck­et.
• The primary buck­et is au­to­mat­i­cal­ly used for up­loads through the web in­ter­face.
• Ad­di­tion­al buck­ets are avail­able via the API. To up­load to a non-pri­ma­ry buck­et, spec­i­fy its buck­etKey in the API re­quest. If buck­etKey is not pro­vid­ed, the pri­ma­ry buck­et will be used.

Re­quire­ments

In ad­di­tion to the API key, the user must pro­vide an ac­tive Buck­et Key.

BUCKET_KEY="snapix_default_bucket"

Re­quest

To spec­i­fy which buck­et to use, you can use the bucketKey field in the API calls. If bucketKey is not spec­i­fied in the API calls, as shown in the ex­am­ples above, the pri­ma­ry buck­et will be used by de­fault.

curl -X POST \
  "https://www.snapix.space/api/v1/images" \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "contentType=image/png" \
  -F "name=test-1.png" \
  -F "image=@./test-1.png" \
  -F "bucketKey=${BUCKET_KEY}" | jq

Re­sponse

The re­sponse is the same as in the pre­vi­ous ex­am­ple. The only dif­fer­ence is that if you are us­ing a cus­tom buck­et, the used space is not count­ed.

Notes

curl -X POST \
  "https://www.snapix.space/api/v1/images" \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "contentType=image/png" \
  -F "name=test-1.png" \
  -F "image=@./test-1.png" \
  -F "bucketKey=${BUCKET_KEY}" \
  -F "prefix=example-prefix/" | jq

Con­vert Im­age On Fly API

Process­es an im­age (pro­vid­ed as bi­na­ry data or URL) di­rect­ly based on the spec­i­fied op­tions (con­vert, re­size, etc.). This op­er­a­tion hap­pens on the fly; the im­age is not stored on the ob­ject stor­age. The con­vert­ed im­age vari­ant is re­turned as a stream.

Re­quire­ments

You must pro­vide an ac­tive API key and have suf­fi­cient App cred­its to per­form the op­er­a­tion.

API_KEY="sk_snapix_apiKey-a1b2c3-placeholder"

Re­quest

Send im­age as bi­na­ry data

curl -X POST \
  "https://www.snapix.space/api/v1/convert" \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "image=@./test-1.webp" \
  --output "test-1_converted.webp"

• If you do not spec­i­fy --output the re­sponse will be a stream of data and curl will not save it to a file.
• If you do not spec­i­fy format via the formatOptions field, the de­fault for­mat of webp will be used as the out­put for­mat.
• This re­quest will con­sume 1 App cred­it.

Send im­age as URL

curl -X POST \
  "https://www.snapix.space/api/v1/convert" \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "url=https://images.snapix.space/abc-123/def-456.png" \
  --output "test-2_converted.webp"

• This re­quest will con­sume 1 App cred­it.

Send im­age as bi­na­ry data with cus­tom op­tions

curl -X POST \
  "https://www.snapix.space/api/v1/convert" \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "contentType=image/webp" \
  -F "image=@./test-1.webp" \
  -F "name=test-1.webp" \
  -F "ratio=1.78" \
  -F 'formatOptions={"format": "avif", "options": {"background": "#FF0"}}' \
  -F 'resizeOptions={"width": 1024}' \
  --output "test-1_converted.avif"

• This re­quest will con­sume 1 App cred­it.
• The ratio, formatOptions and resizeOptions fields are op­tion­al, ref­er­ence the ex­pla­na­tions above for more de­tails, the dif­fer­ence is that here we pass the op­tions as a JSON ob­ject in­stead of an ar­ray.
• The ratio, formatOptions and resizeOptions fields are op­tion­al, ref­er­ence the ex­pla­na­tions above for more de­tails, the dif­fer­ence is that here we pass the op­tions as a JSON ob­ject in­stead of an ar­ray.

Gen­er­ate API

We use Im­age Gen­er­a­tion with Gem­i­ni (also known as Nano Ba­nana) to gen­er­ate im­ages. The cur­rent mod­el in use is gem­i­ni-3-pro-im­age-pre­view.

• Each re­quest sup­ports one re­quired text prompt and one op­tion­al im­age tem­plate.
• We ac­cept also Gen­er­ate­Con­tent­Con­fig via the aiConfig field.

This API is pri­mar­i­ly de­signed to gen­er­ate blog post cov­er im­ages based on the pro­vid­ed prompt text and op­tion­al im­age tem­plate. While the tem­plate is not re­quired, we strong­ly rec­om­mend pro­vid­ing one for the best re­sults.

If you need to en­force a spe­cif­ic as­pect ra­tio, you must sup­ply an im­age tem­plate via ei­ther the url or image field. Only one tem­plate im­age is sup­port­ed. For more de­tails, see:

• How to Con­trol Im­age As­pect Ra­tio in Nano Ba­nana

How it works

1. If the url field is pro­vid­ed, the API first fetch­es the im­age tem­plate.
2. It then re­quests im­age gen­er­a­tion from Gem­i­ni us­ing your prompt text and (op­tion­al­ly) the tem­plate.
3. The gen­er­at­ed im­age is processed - re­sized, con­vert­ed to the re­quest­ed for­mat(s), etc.
4. Fi­nal­ly, the processed im­age is up­loaded to ob­ject stor­age.

The re­sult is a set of op­ti­mized, ready-to-use im­ages.

Each re­quest con­sumes 40 App cred­its for im­age gen­er­a­tion, plus one or more cred­its for im­age pro­cess­ing de­pend­ing on the cho­sen out­put for­mat op­tions.

Re­quire­ments

• You must have at least 40 App cred­its from a paid plan.
• You must pro­vide an ac­tive API key.
• Oth­er re­quire­ments are the same as the Up­load API.

API_KEY="sk_snapix_apiKey-a1b2c3-placeholder"

Gen­er­ate Im­age (POST)

Pro­vide im­age tem­plate as bi­na­ry data, via the image field.

curl -X POST \
  "https://www.snapix.space/api/v1/generate" \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "prompt=An astronaut riding a horse" \
  -F "image=@./test-1.webp" \
  -F 'aiConfig={"topP": 0.95, "temperature": 1}' \
  -F "contentType=image/webp" \
  -F "name=Upload-via-binary" \
  -F "description=Test image description - upload via binary" \
  -F "ratio=1.9" \
  -F 'formatOptions=[{"format": "webp"}, {"format": "avif"}]' \
  -F 'resizeOptions=[{"width": 1200}, {"width": 240}]' | jq

• Con­sumes 40 cred­its for gen­er­a­tion and 4 cred­its for pro­cess­ing.

• The prompt field is re­quired.

• The aiConfig field is op­tion­al, for more de­tails see Gen­er­ate­Con­tent­Con­fig.

• The oth­er fields are doc­u­ment­ed in the Up­load API.

Pro­vide im­age tem­plate as URL, via the url field.

curl -X POST \
  "https://www.snapix.space/api/v1/generate" \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "prompt=An astronaut riding a horse" \
  -F "url=https://images.snapix.space/abc-123/def-456.png"
  -F 'aiConfig={"topP": 0.95, "temperature": 1}' \
  -F "name=upload-via-url" \
  -F "description=Test image description - upload via URL" \
  -F 'formatOptions=[{"format": "webp"}]' \
  -F 'resizeOptions=[{"width": 1200, "height": 630}]' | jq

• Con­sumes 40 cred­its for gen­er­a­tion and 1 cred­it for pro­cess­ing.

Ex­am­ple how to use the aiConfig field

-F 'aiConfig={
  "topP": 0.95,
  "temperature": 0.9,
  "systemInstruction":
    "Preserve the character as shown in the input image (same appearance,
    clothing, face, body, body parts, and body to head aspect ratio).
    Change only the scene: background, lighting, surroundings.
    Make sure the character remains recognizably the same.",
}'

Re­sponse

{
  "data": [
    {
      "id": "95c9e3e1-9c7c-426a-9005-6229b084a183",
      "urlBase": "https://www.snapix.space/2t7YzLFAGr...",
      "bucketKey": "snapix_default_bucket",
      "originalName": "Upload-via-binary 2:[240x126]",
      "description": "Test image description - upload via binary",
      "metadata": [
        {
          "size": 896,
          "idSuffix": "thumb_small",
          "imageInfo": {
            "type": "webp",
            "ratio": 1.9,
            "width": 120,
            "height": 63
          },
          "objectKey": "95c9e3e1-9c7c-426a-9005-6229b084a183-thumb_small.webp",
          "contentType": "image/webp",
          "lastModified": 1759583800560,
          "fileExtension": "webp",
          "optimizationPercent": 100
        },
        {
          "size": 4008,
          "idSuffix": "thumb_big",
          "imageInfo": {
            "type": "webp",
            "ratio": 1.9,
            "width": 320,
            "height": 168
          },
          "objectKey": "95c9e3e1-9c7c-426a-9005-6229b084a183-thumb_big.webp",
          "contentType": "image/webp",
          "lastModified": 1759583800554,
          "fileExtension": "webp",
          "optimizationPercent": 100
        },
        {
          "size": 4368,
          "idSuffix": "240x126",
          "imageInfo": {
            "type": "webp",
            "ratio": 1.9,
            "width": 240,
            "height": 126
          },
          "objectKey": "95c9e3e1-9c7c-426a-9005-6229b084a183-240x126.webp",
          "contentType": "image/webp",
          "lastModified": 1759583800547,
          "fileExtension": "webp",
          "optimizationPercent": 100
        },
        {
          "size": 3951,
          "idSuffix": "240x126",
          "imageInfo": {
            "type": "avif",
            "ratio": 1.9,
            "width": 240,
            "height": 126
          },
          "objectKey": "95c9e3e1-9c7c-426a-9005-6229b084a183-240x126.avif",
          "contentType": "image/avif",
          "lastModified": 1759583800641,
          "fileExtension": "avif",
          "optimizationPercent": 100
        },
        {
          "size": 1716290,
          "idSuffix": "original",
          "imageInfo": {
            "type": "png",
            "ratio": 1.91,
            "width": 1408,
            "height": 736
          },
          "objectKey": null,
          "contentType": "image/webp",
          "lastModified": 1759583800314,
          "fileExtension": "png",
          "optimizationPercent": 0
        }
      ],
      "size": 8319,
      "createdAt": "2025-10-04T13:16:40.433Z",
      "updatedAt": "2025-10-04T13:16:40.965Z",
      "galleries": []
    },
    {
      "id": "26fad869-aeb2-4649-9c4a-839cf8a6cbe2",
      "urlBase": "https://www.snapix.space/2t7YzLFAGr...",
      "bucketKey": "snapix_default_bucket",
      "originalName": "Upload-via-binary 1:[1200x632]",
      "description": "Test image description - upload via binary",
      "metadata": [
        {
          "size": 896,
          "idSuffix": "thumb_small",
          "imageInfo": {
            "type": "webp",
            "ratio": 1.9,
            "width": 120,
            "height": 63
          },
          "objectKey": "26fad869-aeb2-4649-9c4a-839cf8a6cbe2-thumb_small.webp",
          "contentType": "image/webp",
          "lastModified": 1759583800471,
          "fileExtension": "webp",
          "optimizationPercent": 100
        },
        {
          "size": 4008,
          "idSuffix": "thumb_big",
          "imageInfo": {
            "type": "webp",
            "ratio": 1.9,
            "width": 320,
            "height": 168
          },
          "objectKey": "26fad869-aeb2-4649-9c4a-839cf8a6cbe2-thumb_big.webp",
          "contentType": "image/webp",
          "lastModified": 1759583800493,
          "fileExtension": "webp",
          "optimizationPercent": 100
        },
        {
          "size": 42792,
          "idSuffix": "1200x632",
          "imageInfo": {
            "type": "webp",
            "ratio": 1.9,
            "width": 1200,
            "height": 632
          },
          "objectKey": "26fad869-aeb2-4649-9c4a-839cf8a6cbe2-1200x632.webp",
          "contentType": "image/webp",
          "lastModified": 1759583800534,
          "fileExtension": "webp",
          "optimizationPercent": 98
        },
        {
          "size": 28453,
          "idSuffix": "1200x632",
          "imageInfo": {
            "type": "avif",
            "ratio": 1.9,
            "width": 1200,
            "height": 632
          },
          "objectKey": "26fad869-aeb2-4649-9c4a-839cf8a6cbe2-1200x632.avif",
          "contentType": "image/avif",
          "lastModified": 1759583801939,
          "fileExtension": "avif",
          "optimizationPercent": 98
        },
        {
          "size": 1716290,
          "idSuffix": "original",
          "imageInfo": {
            "type": "png",
            "ratio": 1.91,
            "width": 1408,
            "height": 736
          },
          "objectKey": null,
          "contentType": "image/webp",
          "lastModified": 1759583800314,
          "fileExtension": "png",
          "optimizationPercent": 0
        }
      ],
      "size": 71245,
      "createdAt": "2025-10-04T13:16:40.342Z",
      "updatedAt": "2025-10-04T13:16:42.964Z",
      "galleries": []
    }
  ],
  "simpleData": [
    {
      "id": "95c9e3e1-9c7c-426a-9005-6229b084a183",
      "originalName": "Upload-via-binary 2:[240x126]",
      "variants": {
        "webp": "https://snapix-dev-serve.metalevel.tech/2t7YzLFAGr9H7wAHzrHilBzs4yh/95c9e3e1-9c7c-426a-9005-6229b084a183-240x126.webp",
        "avif": "https://snapix-dev-serve.metalevel.tech/2t7YzLFAGr9H7wAHzrHilBzs4yh/95c9e3e1-9c7c-426a-9005-6229b084a183-240x126.avif"
      },
      "info": {
        "width": 240,
        "height": 126,
        "ratio": 1.9
      }
    },
    {
      "id": "26fad869-aeb2-4649-9c4a-839cf8a6cbe2",
      "originalName": "Upload-via-binary 1:[1200x632]",
      "variants": {
        "webp": "https://snapix-dev-serve.metalevel.tech/2t7YzLFAGr9H7wAHzrHilBzs4yh/26fad869-aeb2-4649-9c4a-839cf8a6cbe2-1200x632.webp",
        "avif": "https://snapix-dev-serve.metalevel.tech/2t7YzLFAGr9H7wAHzrHilBzs4yh/26fad869-aeb2-4649-9c4a-839cf8a6cbe2-1200x632.avif"
      },
      "info": {
        "width": 1200,
        "height": 632,
        "ratio": 1.9
      }
    }
  ],
  "accountStatistics": {
    "storageUsed": "user-bucket",
    "totalStorage": "user-bucket",
    "creditsUsed": 44,
    "remainingCredits": 853,
    "remainingCreditsPaidPlans": 520
  },
  "imageGenerateResponse": {
    "metadata": {
      "responseId": "Nh7haKSiH42zxN8PzMe_GA",
      "modelVersion": "gemini-3-pro-image-preview",
      "usageMetadata": {
        "promptTokenCount": 1296,
        "candidatesTokenCount": 1290,
        "totalTokenCount": 2586,
        "promptTokensDetails": [
          {
            "modality": "TEXT",
            "tokenCount": 6
          },
          {
            "modality": "IMAGE",
            "tokenCount": 1290
          }
        ],
        "candidatesTokensDetails": [
          {
            "modality": "IMAGE",
            "tokenCount": 1290
          }
        ]
      }
    },
    "text": ""
  }
}

Gallery Man­age­ment API

Gal­leries al­low you to group and or­ga­nize your im­ages. All Gallery Man­age­ment API end­points re­quire an ac­tive API key. None of these op­er­a­tions con­sume App cred­its; the user's API call rate lim­its are ap­plied.

API_KEY="sk_snapix_apiKey-a1b2c3-placeholder"

Get Gallery List (GET)

Re­turns all gal­leries be­long­ing to the au­then­ti­cat­ed user.

Re­quest

curl -X GET "https://www.snapix.space/api/v1/galleries" \
  -H "Authorization: Bearer ${API_KEY}" | jq

• The re­quest does not cost any App cred­its.

Re­sponse

{
  "galleries": [
    {
      "id": "7618c305-...",
      "name": "My Gallery",
      "isPublic": false,
      "bucketKey": "default",
      "accountId": "a1b2c3d4-...",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-03-15T12:00:00.000Z"
    }
    // More gallery objects...
  ]
}

Cre­ate a Gallery (POST)

Cre­ates a new gallery. Im­ages can op­tion­al­ly be at­tached at cre­ation time.

Re­quest

curl -X POST "https://www.snapix.space/api/v1/galleries" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My New Gallery",
    "isPublic": false,
    "bucketKey": "snapix_default_bucket",
    "imageIds": ["f948f86a-...", "a1b2c3d4-..."]
  }' | jq

• name (re­quired) - gallery name, max 256 char­ac­ters.
• isPublic (op­tion­al) - whether the gallery is pub­licly ac­ces­si­ble. De­faults to false.
• bucketKey (op­tion­al) - the buck­et to as­so­ciate the gallery with. De­faults to the pri­ma­ry buck­et. For more de­tails see the Cus­tom Buck­ets sec­tion.
• imageIds (op­tion­al) - an ar­ray of ex­ist­ing im­age IDs to add to the gallery at cre­ation time.
• The re­quest does not cost any App cred­its.

Re­sponse

{
  "gallery": {
    "id": "7618c305-...",
    "name": "My New Gallery",
    "isPublic": false,
    "bucketKey": "default",
    "accountId": "a1b2c3d4-...",
    "createdAt": "2026-04-04T10:00:00.000Z",
    "updatedAt": null,
    "images": [
      {
        "galleryId": "7618c305-...",
        "imageId": "f948f86a-...",
        "image": { /* image object */ }
      }
      // More image objects...
    ]
  }
}

Get a Gallery (GET)

Re­turns a sin­gle gallery by ID, in­clud­ing the full list of as­so­ci­at­ed im­ages.

Re­quest

curl -X GET "https://www.snapix.space/api/v1/galleries/${ID}" \
  -H "Authorization: Bearer ${API_KEY}" | jq

• Re­place the trail­ing path seg­ment with the gallery UUID.
• The re­quest does not cost any App cred­its.

Re­sponse

{
  "gallery": {
    "id": "7618c305-...",
    "name": "My Gallery",
    "isPublic": false,
    "bucketKey": "default",
    "accountId": "a1b2c3d4-...",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-03-15T12:00:00.000Z",
    "images": [
      {
        "galleryId": "7618c305-...",
        "imageId": "f948f86a-...",
        "image": { /* image object */ }
      }
      // More image objects...
    ]
  }
}

Get Un­grouped Im­ages (GET)

Re­turns all im­ages be­long­ing to the au­then­ti­cat­ed user that are not as­signed to any gallery.

Re­quest

curl -X GET "https://www.snapix.space/api/v1/galleries/ungrouped?bucketKey=my-bucket" \
  -H "Authorization: Bearer ${API_KEY}" | jq

Query Pa­ra­me­ters

• The re­quest does not cost any App cred­its.

Re­sponse

{
  "gallery": {
    "id": "ungrouped",
    "name": "Ungrouped",
    "isPublic": false,
    "bucketKey": "default",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": null,
    "accountId": "acc-...",
    "images": [
      {
        "galleryId": "ungrouped",
        "imageId": "f948f86a-...",
        "image": {
          "id": "f948f86a-...",
          "urlBase": "https://cdn.example.com",
          "originalName": "my-photo.png",
          "description": null,
          "metadata": [ /* variant objects */ ],
          "size": 204800,
          "bucketKey": "default",
          "createdAt": "2026-01-01T00:00:00.000Z",
          "updatedAt": null,
          "galleries": []
        }
      }
      // More image entries...
    ]
  }
}

Up­date a Gallery (PATCH/PUT)

Up­dates the name and/or isPublic fields of an ex­ist­ing gallery. At least one field must be pro­vid­ed.

Both PATCH /api/v1/galleries/${ID} and PUT /api/v1/galleries/${ID} be­have iden­ti­cal­ly - only the fields pro­vid­ed in the re­quest body are up­dat­ed.

Re­quest

curl -X PATCH "https://www.snapix.space/api/v1/galleries/${ID}" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "isPublic": true}' | jq

• You must pro­vide at least one of name or isPublic; oth­er­wise the re­quest will be re­ject­ed.
• The re­quest does not cost any App cred­its.

Re­sponse

{
  "id": "7618c305-...",
  "name": "Updated Name",
  "isPublic": true,
  "bucketKey": "default",
  "accountId": "a1b2c3d4-...",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-04-04T11:00:00.000Z"
}

Delete a Gallery (DELETE)

Deletes a gallery by ID. Op­tion­al­ly, all im­ages as­so­ci­at­ed with the gallery can be per­ma­nent­ly re­moved from stor­age at the same time.

Re­quest

# Delete the gallery only (images are kept)
curl -X DELETE "https://www.snapix.space/api/v1/galleries/${ID}" \
  -H "Authorization: Bearer ${API_KEY}"

# Delete the gallery and permanently remove all its images from storage
curl -X DELETE "https://www.snapix.space/api/v1/galleries/${ID}?deleteImages=true" \
  -H "Authorization: Bearer ${API_KEY}"

• deleteImages query pa­ra­me­ter (op­tion­al, de­fault false):
  • false - deletes only the gallery record; all im­ages re­main in stor­age and in your ac­count.
  • true - deletes the gallery and per­ma­nent­ly re­moves all its im­ages from stor­age. The gallery's bucketKey is used to lo­cate the im­ages in the cor­rect buck­et.
• The re­quest does not cost any App cred­its.

Re­sponse

null