> ## 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.

# Create Story

> Create image and video stories with StoryRepository creation APIs.

Use the story repository to create image or video stories for a target. The examples below use community targets, optional metadata, and an optional hyperlink story item.

Story creation is optimistic on the SDKs that maintain local story state. Watch the returned story or active story collection for sync state changes such as syncing, synced, or failed.

## Parameters

| Concept     | TypeScript                      | iOS                  | Android                           | Flutter                          |
| ----------- | ------------------------------- | -------------------- | --------------------------------- | -------------------------------- |
| Target type | `'community'`                   | `.community`         | `AmityStory.TargetType.COMMUNITY` | `AmityStoryTargetType.COMMUNITY` |
| Target ID   | `string`                        | `String`             | `String`                          | `String`                         |
| Image input | `FormData` with `files`         | `imageFileURL`       | `imageUri`                        | `imageFile`                      |
| Video input | `FormData` with `files`         | `videoFileURL`       | `videoUri`                        | `videoFile`                      |
| Metadata    | Object                          | `[String: Any]?`     | `JsonObject?`                     | `Map<String, dynamic>?`          |
| Hyperlinks  | `Amity.StoryItemType.Hyperlink` | `AmityHyperLinkItem` | `AmityStoryItem.HYPERLINK`        | `HyperLink`                      |

<Note>
  For TypeScript, append the file under the `files` key. The SDK throws if the `FormData` object has no `files` entry.
</Note>

## Create image story

Create an image story from a local image file, target, and optional metadata or hyperlink items.

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

  const formData = new FormData();
  formData.append('files', imageFile);

  const result = await StoryRepository.createImageStory(
    'community',
    communityId,
    formData,
    { campaignId: 'launch' },
    'fit',
    [
      {
        type: Amity.StoryItemType.Hyperlink,
        data: {
          url: 'https://example.com',
          customText: 'Learn more',
        },
      },
    ],
  );

  renderResults(result.data);
  ```

  ```swift iOS theme={null}
  let items: [AmityStoryItem] = [
      AmityHyperLinkItem(url: "https://example.com", customText: "Learn more")
  ]

  let imageURL = URL(fileURLWithPath: "/path/to/image.jpg")
  let options = AmityImageStoryCreateOptions(
      targetType: .community,
      targetId: communityId,
      imageFileURL: imageURL,
      metadata: ["campaignId": "launch"],
      items: items,
      imageDisplayMode: .fit
  )

  let story = try await storyRepository.createImageStory(options: options)
  showSuccessMessage(story.storyId)
  ```

  ```kotlin Android theme={null}
  fun createImageStory(
      storyRepository: AmityStoryRepository,
      targetId: String,
      imageUri: Uri
  ) {
      storyRepository.createImageStory(
          targetType = AmityStory.TargetType.COMMUNITY,
          targetId = targetId,
          imageUri = imageUri,
          storyItems = listOf(
              AmityStoryItem.HYPERLINK(
                  url = "https://example.com",
                  customText = "Learn more"
              )
          ),
          imageDisplayMode = AmityStoryImageDisplayMode.FIT,
          metadata = JsonObject().apply {
              addProperty("campaignId", "launch")
          }
      )
          .doOnComplete { showSuccessMessage("Story created") }
          .doOnError { error -> showErrorMessage(error = error) }
          .subscribe()
  }
  ```

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

  Future<void> createImageStory(String communityId) async {
    final storyRepository = AmitySocialClient.newStoryRepository();

    await storyRepository.createImageStory(
      targetType: AmityStoryTargetType.COMMUNITY,
      targetId: communityId,
      imageFile: File('/path/to/image.jpg'),
      imageDisplayMode: AmityStoryImageDisplayMode.FIT,
      metadata: {'campaignId': 'launch'},
      storyItems: [
        HyperLink(
          url: 'https://example.com',
          customText: 'Learn more',
        ),
      ],
    );
  }
  ```
</CodeGroup>

## Create video story

Create a video story from a local video file, target, and optional metadata or hyperlink items.

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

  const formData = new FormData();
  formData.append('files', videoFile);

  const result = await StoryRepository.createVideoStory(
    'community',
    communityId,
    formData,
    { campaignId: 'launch' },
    [
      {
        type: Amity.StoryItemType.Hyperlink,
        data: {
          url: 'https://example.com',
          customText: 'Watch more',
        },
      },
    ],
  );

  renderResults(result.data);
  ```

  ```swift iOS theme={null}
  let items: [AmityStoryItem] = [
      AmityHyperLinkItem(url: "https://example.com", customText: "Watch more")
  ]

  let videoURL = URL(fileURLWithPath: "/path/to/video.mp4")
  let options = AmityVideoStoryCreateOptions(
      targetType: .community,
      targetId: communityId,
      videoFileURL: videoURL,
      metadata: ["campaignId": "launch"],
      items: items
  )

  let story = try await storyRepository.createVideoStory(options: options)
  showSuccessMessage(story.storyId)
  ```

  ```kotlin Android theme={null}
  fun createVideoStory(
      storyRepository: AmityStoryRepository,
      targetId: String,
      videoUri: Uri
  ) {
      storyRepository.createVideoStory(
          targetType = AmityStory.TargetType.COMMUNITY,
          targetId = targetId,
          videoUri = videoUri,
          storyItems = listOf(
              AmityStoryItem.HYPERLINK(
                  url = "https://example.com",
                  customText = "Watch more"
              )
          ),
          metadata = JsonObject().apply {
              addProperty("campaignId", "launch")
          }
      )
          .doOnComplete { showSuccessMessage("Story created") }
          .doOnError { error -> showErrorMessage(error = error) }
          .subscribe()
  }
  ```

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

  Future<void> createVideoStory(String communityId) async {
    final storyRepository = AmitySocialClient.newStoryRepository();

    await storyRepository.createVideoStory(
      targetType: AmityStoryTargetType.COMMUNITY,
      targetId: communityId,
      videoFile: File('/path/to/video.mp4'),
      metadata: {'campaignId': 'launch'},
      storyItems: [
        HyperLink(
          url: 'https://example.com',
          customText: 'Watch more',
        ),
      ],
    );
  }
  ```
</CodeGroup>

## Hyperlink items

Story hyperlink items contain:

| Field        | Description                       |
| ------------ | --------------------------------- |
| `url`        | Destination URL.                  |
| `customText` | Optional text shown for the link. |

## Related topics

<CardGroup cols={2}>
  <Card title="Get Stories" href="../retrieval/get-stories" icon="list">
    Observe created stories and sync state.
  </Card>

  <Card title="Story Impressions" href="../analytics/story-impressions" icon="chart-bar">
    Mark synced stories as seen and track link clicks.
  </Card>
</CardGroup>