Upload image

Upload a new PNG, JPEG, or WebP image with optional metadata. Duplicate images, and requests larger than 16MB will be rejected.

Endpoint

POST /accounts/{accountID}/images

Request Example

curl -X POST "https://api.moov.io/accounts/{accountID}/images" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.04.00" \
  -F "image=@/path/to/image" \
  -F 'metadata={}'

Node.js Example

import { Moov } from "@moovio/sdk";
import { openAsBlob } from "node:fs";

const moov = new Moov({
  security: {
    username: "",
    password: "",
  },
});

async function run() {
  const result = await moov.images.upload({
    accountID: "c0971a52-1f1c-4511-876a-f45c4cfd6154",
    imageUploadRequestMultiPart: {
      image: await openAsBlob("example.file"),
    },
  });

console.log(result);
}

run();

PHP Example

declare(strict_types=1);

require 'vendor/autoload.php';

use Moov\MoovPhp;
use Moov\MoovPhp\Models\Components;

$sdk = MoovPhp\Moov::builder()
    ->setSecurity(
        new Components\Security(
            username: '',
            password: '',
        )
    )
    ->build();

$imageUploadRequestMultiPart = new Components\ImageUploadRequestMultiPart(
    image: new Components\Image(
        fileName: 'example.file',
        content: file_get_contents('example.file');,
    ),
);

$response = $sdk->images->upload(
    accountID: 'c0971a52-1f1c-4511-876a-f45c4cfd6154',
    imageUploadRequestMultiPart: $imageUploadRequestMultiPart
);

if ($response->imageMetadata !== null) {
    // handle response
}

Java Example

package hello.world;

import io.moov.sdk.Moov;
import io.moov.sdk.models.components.*;
import io.moov.sdk.models.errors.GenericError;
import io.moov.sdk.models.errors.ImageRequestValidationError;
import io.moov.sdk.models.operations.UploadImageResponse;
import io.moov.sdk.utils.Utils;
import java.io.FileInputStream;
import java.lang.Exception;

public class Application {

public static void main(String[] args) throws GenericError, ImageRequestValidationError, Exception {

Moov sdk = Moov.builder()
                .security(Security.builder()
                    .username("")
                    .password("")
                    .build())
            .build();

UploadImageResponse res = sdk.images().upload()
                .accountID("c0971a52-1f1c-4511-876a-f45c4cfd6154")
                .imageUploadRequestMultiPart(ImageUploadRequestMultiPart.builder()
                    .image(Image.builder()
                        .fileName("example.file")
                        .content(Utils.readBytesAndClose(new FileInputStream("example.file")))
                        .build())
                    .build())
                .call();

}
}

Python Example

from moovio_sdk import Moov
from moovio_sdk.models import components

with Moov(
    security=components.Security(
        username="",
        password="",
    ),
) as moov:

res = moov.images.upload(account_id="c0971a52-1f1c-4511-876a-f45c4cfd6154", image={
        "file_name": "example.file",
        "content": open("example.file", "rb"),
    })

# Handle response
    print(res)

Ruby Example

require 'moov_ruby'

Models = ::Moov::Models
s = ::Moov::Client.new(
  security: Models::Components::Security.new(
    username: '',
    password: ''
  )
)
res = s.images.upload(account_id: 'c0971a52-1f1c-4511-876a-f45c4cfd6154', image_upload_request_multi_part: Models::Components::ImageUploadRequestMultiPart.new(
  image: Models::Components::Image.new(
    file_name: 'example.file',
    content: File.binread('example.file')
  )
))

unless res.image_metadata.nil?
  # handle response
end

C# Example

using Moov.Sdk;
using Moov.Sdk.Models.Components;

var sdk = new MoovClient(security: new Security() {
    Username = "",
    Password = "",
});

var res = await sdk.Images.UploadAsync(
    accountID: "c0971a52-1f1c-4511-876a-f45c4cfd6154",
    body: new ImageUploadRequestMultiPart() {
        Image = new Image() {
            FileName = "example.file",
            Content = System.IO.File.ReadAllBytes("example.file"),
        },
    }
);

// handle response

Response Metadata

Example:

{
  "imageID": "string",
  "publicID": "string",
  "altText": "string",
  "link": "https://api.moov.io/images/qJRAaAwwF5hmfeAFdHjIb",
  "createdOn": "2019-08-24T14:15:22Z",
  "updatedOn": "2019-08-24T14:15:22Z",
  "disabledOn": "2019-08-24T14:15:22Z"
}

Possible Error Responses

1. Invalid Syntax
   Example:

   {
     "error": "string"
   }
   

2. Missing Authentication
   Example:

   {
     "error": "string"
   }
   

3. Unauthorized
   Example:

   {
     "error": "string"
   }
   

4. Resource Not Found
   Example:

   {
     "error": "string"
   }
   

5. Request Conflict
   Example:

   {
     "error": "string"
   }
   

6. Validation Error
   Example:

   {
     "image": "string",
     "metadata": {
       "altText": "string"
     }
   }
   

7. Rate Limiting

8. Unexpected Error

9. Downstream Service Failure

Additional Information

Set this header to v2026.04.00 to use the API described in this specification.

Image Upload/Metadata Info

• Image file format: PNG, JPEG, or WebP.
• Optional JSON-encoded metadata for the uploaded image.