feat(image): add AI-generated avatars

src/modules/image/index.ts

@@ -1,6 +1,7 @@
 import { toBase64 } from '../../internal/base64';
 import { deprecated } from '../../internal/deprecated';
 import { ModuleBase } from '../../internal/module-base';
+import type { SexType } from '../person';
 
 /**
  * Module to generate images.
@@ -27,7 +28,11 @@ export class ImageModule extends ModuleBase {
    */
   avatar(): string {
     // Add new avatar providers here, when adding a new one.
-    return this.avatarGitHub();
+    const avatarMethod = this.faker.helpers.arrayElement([
+      this.avatarAI,
+      this.avatarGitHub,
+    ]);
+    return avatarMethod();
   }
 
   /**
@@ -45,6 +50,35 @@ export class ImageModule extends ModuleBase {
     )}`;
   }
 
+  /**
+   * Generates a random avatar generated by AI. These are currently images of people which were generated by Stable Diffusion 3. The image URLs are served via the JSDelivr CDN and subject to their [terms of use](https://www.jsdelivr.com/terms).
+   *
+   * @param options Options for generating an AI avatar.
+   * @param options.sex The sex of the person for the avatar. Can be 'female' or 'male'. If not provided, defaults to a random selection.
+   *
+   * @example
+   * faker.image.avatarAI()
+   * // 'https://cdn.jsdelivr.net/.../female/32.jpg'
+   * faker.image.avatarAI({ sex: 'male' })
+   * // 'https://cdn.jsdelivr.net/.../male/32.jpg'
+   *
+   * @since 9.1.0
+   */
+  avatarAI(options?: {
+    /**
+     * The sex of the person for the avatar.
+     * Can be 'female' or 'male'.
+     * If not provided, defaults to a random selection.
+     */
+    sex?: SexType;
+  }): string {
+    const type = options?.sex ?? this.faker.person.sexType();
+    // FIXME: This should be replaced by the final CDN url, presumably something like: 'https://cdn.jsdelivr.net/gh/faker-js/faker-media/avatars_ai'
+    const baseURL =
+      'https://cdn.jsdelivr.net/gh/matthewmayer/sd3-avatars@country-prompt';
+    return `${baseURL}/${type}/${this.faker.number.int({ min: 1, max: 50 })}.jpg`;
+  }
+
   /**
    * Generates a random avatar from `https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar`.
    *

test/modules/__snapshots__/image.spec.ts.snap

@@ -1,6 +1,10 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`image > 42 > avatar 1`] = `"https://avatars.githubusercontent.com/u/37454012"`;
+exports[`image > 42 > avatar 1`] = `"https://cdn.jsdelivr.net/gh/matthewmayer/sd3-avatars@country-prompt/male/37.jpg"`;
+
+exports[`image > 42 > avatarAI > noArgs 1`] = `"https://cdn.jsdelivr.net/gh/matthewmayer/sd3-avatars@country-prompt/female/48.jpg"`;
+
+exports[`image > 42 > avatarAI > with sex 1`] = `"https://cdn.jsdelivr.net/gh/matthewmayer/sd3-avatars@country-prompt/female/19.jpg"`;
 
 exports[`image > 42 > avatarGitHub 1`] = `"https://avatars.githubusercontent.com/u/37454012"`;
 
@@ -76,7 +80,11 @@ exports[`image > 42 > urlPlaceholder > with width 1`] = `"https://via.placeholde
 
 exports[`image > 42 > urlPlaceholder > with width and height 1`] = `"https://via.placeholder.com/128x128/8ead33/1ddf0f.webp?text=benevolentia%20attonbitus%20auctus"`;
 
-exports[`image > 1211 > avatar 1`] = `"https://avatars.githubusercontent.com/u/92852016"`;
+exports[`image > 1211 > avatar 1`] = `"https://avatars.githubusercontent.com/u/89347165"`;
+
+exports[`image > 1211 > avatarAI > noArgs 1`] = `"https://cdn.jsdelivr.net/gh/matthewmayer/sd3-avatars@country-prompt/male/45.jpg"`;
+
+exports[`image > 1211 > avatarAI > with sex 1`] = `"https://cdn.jsdelivr.net/gh/matthewmayer/sd3-avatars@country-prompt/female/47.jpg"`;
 
 exports[`image > 1211 > avatarGitHub 1`] = `"https://avatars.githubusercontent.com/u/92852016"`;
 
@@ -152,7 +160,11 @@ exports[`image > 1211 > urlPlaceholder > with width 1`] = `"https://via.placehol
 
 exports[`image > 1211 > urlPlaceholder > with width and height 1`] = `"https://via.placeholder.com/128x128/ed4fef/a7fbae.webp?text=dapifer%20usque%20unde"`;
 
-exports[`image > 1337 > avatar 1`] = `"https://avatars.githubusercontent.com/u/26202467"`;
+exports[`image > 1337 > avatar 1`] = `"https://cdn.jsdelivr.net/gh/matthewmayer/sd3-avatars@country-prompt/female/14.jpg"`;
+
+exports[`image > 1337 > avatarAI > noArgs 1`] = `"https://cdn.jsdelivr.net/gh/matthewmayer/sd3-avatars@country-prompt/female/8.jpg"`;
+
+exports[`image > 1337 > avatarAI > with sex 1`] = `"https://cdn.jsdelivr.net/gh/matthewmayer/sd3-avatars@country-prompt/female/14.jpg"`;
 
 exports[`image > 1337 > avatarGitHub 1`] = `"https://avatars.githubusercontent.com/u/26202467"`;
 

test/modules/image.spec.ts

@@ -89,6 +89,10 @@ describe('image', () => {
           type: 'svg-uri',
         });
     });
+
+    t.describe('avatarAI', (t) => {
+      t.it('noArgs').it('with sex', { sex: 'female' });
+    });
   });
 
   describe('avatar', () => {
@@ -124,6 +128,16 @@ describe('image', () => {
     });
   });
 
+  describe('avatarAI', () => {
+    it('should return a random avatar url from AI', () => {
+      const avatarUrl = faker.image.avatarAI();
+
+      expect(avatarUrl).toBeTypeOf('string');
+      expect(avatarUrl).toMatch(/^https:\/\/cdn\.jsdelivr\.net\/.*\.jpg$/);
+      expect(() => new URL(avatarUrl)).not.toThrow();
+    });
+  });
+
   describe('url', () => {
     it('should return a random image url', () => {
       const imageUrl = faker.image.url();