> ## Documentation Index
> Fetch the complete documentation index at: https://learn.social.plus/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Handling

> Upload images, read image metadata, and request sized image URLs with the Social+ SDKs.

Use image handling when your app needs to upload image files for avatars, posts, comments, messages, stories, or other media surfaces. Image uploads return image file data with a `fileId`, URL, metadata, access type, and, on supported platforms, alt text.

For image posts, comments, messages, and avatars, first upload the image through the file repository, then pass the returned image object or `fileId` into the relevant creation or update API.

## Platform Surface

| Platform   | Upload                                                                                                                  | Fetch                                                                          | Sized URLs                                                                               | Alt text                                               |
| ---------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| TypeScript | `FileRepository.uploadImage(formData, onProgress?, altText?)`                                                           | `FileRepository.getFile(fileId)`                                               | `FileRepository.fileUrlWithSize(fileUrl, size)` with `small`, `medium`, `large`, `full`  | Upload and `updateAltText(fileId, altText)`            |
| iOS        | `AmityFileRepository.uploadImage(_:altText:progress:)` and `uploadImage(with:isFullImage:altText:progress:completion:)` | `getFile(fileId:)`, then `mapToImageData()`                                    | `downloadImage(fromURL:size:)` with `AmityMediaSize.small`, `.medium`, `.large`, `.full` | Upload and `updateAltText(fileId:altText:)`            |
| Android    | `AmityCoreClient.newFileRepository().uploadImage(uri, altText?)`                                                        | `getFile(fileId)`, then `asAmityImage()`                                       | `AmityImage.getUrl(AmityImage.Size)` with `SMALL`, `MEDIUM`, `LARGE`                     | Upload and `updateAltText(fileId, altText)`            |
| Flutter    | `AmityCoreClient.newFileRepository().uploadImage(file, isFullImage?)`                                                   | Not exposed as a direct public file-repository fetch method in the current SDK | `AmityImage.getUrl(AmityImageSize)` with `SMALL`, `MEDIUM`, `LARGE`, `FULL`              | No public upload alt-text parameter in the current SDK |

## Parameters

| Parameter                                     | Platforms                         | Description                                                                                                                                                 |
| --------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `formData` / `image` / `url` / `uri` / `file` | TypeScript, iOS, Android, Flutter | The image input. TypeScript accepts `FormData`; iOS accepts `UIImage` or a local image `URL`; Android accepts `Uri`; Flutter accepts `File`.                |
| `altText`                                     | TypeScript, iOS, Android          | Optional accessibility text stored on the image file. Flutter's current public upload method does not expose this parameter.                                |
| `isFullImage`                                 | iOS, Flutter                      | Whether the uploaded image should be treated as the full image. iOS documents this on the URL-based upload; Flutter exposes `isFullImage` on public upload. |
| `fileId`                                      | TypeScript, iOS, Android          | ID returned by upload or embedded in content data. Used for direct fetch, size lookup, or alt-text update where available.                                  |
| `size`                                        | TypeScript, iOS, Android, Flutter | Requested display size. Size names differ slightly by platform, and Android currently exposes `SMALL`, `MEDIUM`, and `LARGE`.                               |
| `onProgress` / `progress`                     | TypeScript, iOS, Android, Flutter | Upload progress callback or stream event.                                                                                                                   |

## Upload An Image

Upload an image first, then use the returned image object or `fileId` in avatar, post, comment, message, or story APIs.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { FileRepository } from '@amityco/ts-sdk';

  async function uploadImage(image: File) {
    const formData = new FormData();
    formData.append('file', image);

    const { data: images } = await FileRepository.uploadImage(
      formData,
      percent => {
        console.log(`Upload progress: ${percent}%`);
      },
      'Profile photo',
    );

    return images[0].fileId;
  }
  ```

  ```swift iOS theme={null}
  let image = UIImage()

  let uploadedImage = try await fileRepository.uploadImage(
      image,
      altText: "Profile photo",
      progress: { progress in
          print("Upload progress: \(progress)")
      }
  )

  let imageFileId = uploadedImage.fileId
  ```

  ```kotlin Android theme={null}
  val imageUri = Uri.parse("file:///tmp/profile.jpg")

  AmityCoreClient.newFileRepository()
      .uploadImage(uri = imageUri, altText = "Profile photo")
      .doOnNext { result: AmityUploadResult<AmityImage> ->
          when (result) {
              is AmityUploadResult.PROGRESS -> {
                  val progress = result.getUploadInfo().getProgressPercentage()
              }
              is AmityUploadResult.COMPLETE -> {
                  val uploadedImage = result.getFile()
                  val imageFileId = uploadedImage.getFileId()
              }
              is AmityUploadResult.ERROR -> {
                  val error = AmityError.from(result.getError())
              }
              is AmityUploadResult.CANCELLED -> {
                  // Upload was canceled.
              }
          }
      }
      .subscribe()
  ```

  ```dart Flutter theme={null}
  import 'dart:io';

  final image = File('/tmp/profile.jpg');

  AmityCoreClient.newFileRepository()
      .uploadImage(image, isFullImage: true)
      .stream
      .listen((AmityUploadResult<AmityImage> result) {
    result.when(
      progress: (uploadInfo, cancelToken) {
        final progress = uploadInfo.getProgressPercentage();
      },
      complete: (uploadedImage) {
        final imageFileId = uploadedImage.fileId;
        final fullImageUrl = uploadedImage.getUrl(AmityImageSize.FULL);
      },
      error: (error) {
        final exception = error;
      },
      cancel: () {
        // Upload was canceled.
      },
    );
  });
  ```
</CodeGroup>

## Read Image Data

Read image data when your app needs image dimensions, alt text, or a sized image URL for rendering.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { FileRepository } from '@amityco/ts-sdk';

  async function getImage(imageFileId: string) {
    const { data: image } = await FileRepository.getFile<'image'>(imageFileId);
    const mediumUrl = FileRepository.fileUrlWithSize(image.fileUrl, 'medium');

    return {
      mediumUrl,
      altText: image.altText,
      width: image.attributes.metadata.width,
      height: image.attributes.metadata.height,
    };
  }
  ```

  ```swift iOS theme={null}
  let rawFile = try await fileRepository.getFile(fileId: imageFileId)

  if rawFile.type == .image, let imageData = rawFile.mapToImageData() {
      let width = imageData.metadata["width"] as? Int
      let height = imageData.metadata["height"] as? Int

      fileRepository.downloadImage(fromURL: imageData.fileURL, size: .medium) { localURL, error in
          print("Downloaded image: \(String(describing: localURL))")
      }
  }
  ```

  ```kotlin Android theme={null}
  AmityCoreClient.newFileRepository()
      .getFile(imageFileId)
      .doOnSuccess { rawFile: AmityRawFile ->
          val image = rawFile.asAmityImage()
          val mediumUrl = image?.getUrl(AmityImage.Size.MEDIUM)
          val width = image?.getWidth()
          val height = image?.getHeight()
          val altText = image?.getAltText()
      }
      .subscribe()
  ```

  ```dart Flutter theme={null}
  void inspectImage(AmityImage image) {
    final mediumUrl = image.getUrl(AmityImageSize.MEDIUM);
    final width = image.getWidth();
    final height = image.getHeight();
    final isFullImage = image.isFullImage();
  }
  ```
</CodeGroup>

## Related Topics

<CardGroup cols={3}>
  <Card title="Image Posts" icon="image" href="/social-plus-sdk/social/content-management/posts/creation/image-post">
    Attach uploaded images to social posts.
  </Card>

  <Card title="Image Comments" icon="message" href="/social-plus-sdk/social/content-management/comments/creation/image-comment">
    Attach uploaded images to comments.
  </Card>

  <Card title="File Handling" icon="file" href="./file">
    Upload and inspect generic file attachments.
  </Card>
</CardGroup>