> For the complete documentation index, see [llms.txt](https://shortgenius.gitbook.io/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shortgenius.gitbook.io/api/guides/image-generation.md).

# Image Generation

ShortGenius includes a powerful AI image generation feature. By providing a text prompt and specifying an aspect ratio (and optionally an image style), you can quickly create unique visuals for your projects. This section covers creating, listing, retrieving, and customizing images.

## Creating Images

**Endpoint**: `POST /images`

### Basic Example

{% tabs %}
{% tab title="TypeScript" %}

```typescript
import { ShortGenius } from 'shortgenius'

const client = new ShortGenius({
  bearerAuth: 'YOUR_API_TOKEN'
})

const image = await client.createImage({
  prompt: 'A futuristic cityscape at sunset',
  aspectRatio: '9:16',
  waitForGeneration: true
})

console.log(`Image created: ${image.id}`)
console.log(`URL: ${image.url}`)
```

{% endtab %}

{% tab title="Python" %}

```python
from shortgenius import Shortgenius

client = Shortgenius(api_key="YOUR_API_TOKEN")

image = client.images.create(
    prompt="A futuristic cityscape at sunset",
    aspect_ratio="9:16",
    wait_for_generation=True
)

print(f"Image created: {image.id}")
print(f"URL: {image.url}")
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request POST \
  --url "https://api.shortgenius.com/v1/images" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "prompt": "A futuristic cityscape at sunset",
    "aspect_ratio": "9:16",
    "wait_for_generation": true
  }'
```

{% endtab %}
{% endtabs %}

**Key Fields**:

| Field                 | Type    | Required | Description                                                                                                                              |
| --------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`              | string  | Yes      | Text prompt for image creation.                                                                                                          |
| `aspect_ratio`        | string  | Yes      | One of `"9:16"`, `"16:9"`, or `"1:1"`.                                                                                                   |
| `image_style_id`      | string  | No       | An optional style preset. Retrieve available styles via **GET** `/images/styles`.                                                        |
| `scene_id`            | string  | No       | If you want to attach this generated image to a particular video scene.                                                                  |
| `wait_for_generation` | boolean | No       | If **false**, the API returns immediately, and you must poll to see the final image. If **true**, it waits until the image is generated. |

#### Sample Response (Synchronous)

If `wait_for_generation` is **true**, and generation succeeds quickly, you might get a response like:

```json
{
  "id": "b3e48cbd-7f89-4bd0-a9ad-f2f0afef63a3",
  "url": "https://cdn.shortgenius.com/images/b3e48cbd.jpg",
  "type": "GeneratedImage",
  "state": "completed",
  "created_at": "2025-05-01T12:00:00Z",
  "updated_at": null,
  "prompt": "A futuristic cityscape at sunset",
  "is_nsfw": false,
  "aspect_ratio": "9:16",
  "image_style_id": null
}
```

If `wait_for_generation` is **false**, you might see `state: "pending"` or `state: "generating"`, and you'll need to poll the **GET** endpoint until the state becomes `"completed"`.

***

## Retrieving Images

You can list all images you've generated or retrieve a single one by its ID.

### List Images

**Endpoint**: `GET /images`

| Query Param | Default | Description                      |
| ----------- | ------- | -------------------------------- |
| `page`      | 0       | Results page number (zero-based) |
| `limit`     | 50      | Items per page, up to 200        |

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const response = await client.getImages({
  page: 0,
  limit: 10
})

console.log(`Found ${response.images.length} images`)

for (const image of response.images) {
  console.log(`- ${image.prompt} (${image.id})`)
  console.log(`  URL: ${image.url}`)
  console.log(`  State: ${image.state}`)
}
```

{% endtab %}

{% tab title="Python" %}

```python
response = client.images.list(page=0, limit=10)

print(f"Found {len(response.images)} images")

for image in response.images:
    print(f"- {image.prompt} ({image.id})")
    print(f"  URL: {image.url}")
    print(f"  State: {image.state}")
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET \
  --url "https://api.shortgenius.com/v1/images?page=0&limit=10" \
  --header "Authorization: Bearer YOUR_API_TOKEN"
```

{% endtab %}
{% endtabs %}

### Retrieve a Single Image

**Endpoint**: `GET /images/{id}`

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const image = await client.getImage('b3e48cbd-7f89-4bd0-a9ad-f2f0afef63a3')

console.log(`URL: ${image.url}`)
console.log(`State: ${image.state}`)
console.log(`Aspect Ratio: ${image.aspectRatio}`)
```

{% endtab %}

{% tab title="Python" %}

```python
image = client.images.retrieve("b3e48cbd-7f89-4bd0-a9ad-f2f0afef63a3")

print(f"Prompt: {image.prompt}")
print(f"URL: {image.url}")
print(f"State: {image.state}")
print(f"Aspect Ratio: {image.aspect_ratio}")
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET \
  --url "https://api.shortgenius.com/v1/images/b3e48cbd-7f89-4bd0-a9ad-f2f0afef63a3" \
  --header "Authorization: Bearer YOUR_API_TOKEN"
```

{% endtab %}
{% endtabs %}

***

## Image Styles

ShortGenius offers numerous **image styles** that apply artistic filters or aesthetic themes to your generated images. You can retrieve all available styles and use their IDs during image creation.

### List Image Styles

**Endpoint**: `GET /images/styles`

{% tabs %}
{% tab title="TypeScript" %}

```typescript
const styles = await client.getImageStyles()

console.log(`Found ${styles.length} image styles:`)

for (const style of styles) {
  console.log(`- ${style.name} (${style.id})`)
  console.log(`  Prompt: ${style.prompt}`)
  console.log(`  Examples: ${style.examples.join(', ')}`)
}
```

{% endtab %}

{% tab title="Python" %}

```python
styles = client.images.list_styles()

print(f"Found {len(styles)} image styles:")

for style in styles:
    print(f"- {style.name} ({style.id})")
    print(f"  Prompt: {style.prompt}")
    print(f"  Examples: {', '.join(style.examples)}")
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl --request GET \
  --url "https://api.shortgenius.com/v1/images/styles" \
  --header "Authorization: Bearer YOUR_API_TOKEN"
```

{% endtab %}
{% endtabs %}

You can use these IDs in the `image_style_id` field when creating images:

{% tabs %}
{% tab title="TypeScript" %}

```typescript
// Get available styles
const styles = await client.getImageStyles()
const cyberpunkStyle = styles.find(s => s.name === 'Cyberpunk')

// Create image with style
const image = await client.createImage({
  prompt: 'A robotic cat with glowing eyes',
  aspectRatio: '9:16',
  imageStyleId: cyberpunkStyle?.id,
  waitForGeneration: true
})
```

{% endtab %}

{% tab title="Python" %}

```python
# Get available styles
styles = client.images.list_styles()
cyberpunk_style = next((s for s in styles if s.name == "Cyberpunk"), None)

# Create image with style
image = client.images.create(
    prompt="A robotic cat with glowing eyes",
    aspect_ratio="9:16",
    image_style_id=cyberpunk_style.id if cyberpunk_style else None,
    wait_for_generation=True
)
```

{% endtab %}

{% tab title="cURL" %}

```bash
--data '{
  "prompt": "A robotic cat with glowing eyes",
  "aspect_ratio": "9:16",
  "image_style_id": "01b28da2-96fa-42f9-9efc-3d17ff042882"
}'
```

{% endtab %}
{% endtabs %}

***

## Attaching Images to Videos

While drafting or creating videos, you can include AI-generated images in the video scenes, by either:

1. Generating the image first, then embedding the `id` or `url` into a scene.
2. Specifying a `scene_id` when calling `POST /images`, so the platform automatically associates it.

Here's a simplified example of attaching an existing image to a video scene:

{% tabs %}
{% tab title="TypeScript" %}

```typescript
// Generate image first
const image = await client.createImage({
  prompt: 'A futuristic city skyline',
  aspectRatio: '9:16',
  waitForGeneration: true
})

// Use image in video creation
const video = await client.createVideo({
  // ... other fields ...
  scenes: [
    {
      title: 'Intro',
      caption: 'Check out this futuristic city!',
      first_image_id: image.id
    }
  ]
})
```

{% endtab %}

{% tab title="Python" %}

```python
# Generate image first
image = client.images.create(
    prompt="A futuristic city skyline",
    aspect_ratio="9:16",
    wait_for_generation=True
)

# Use image in video creation
video = client.videos.create(
    # ... other fields ...
    scenes=[
        {
            "title": "Intro",
            "caption": "Check out this futuristic city!",
            "first_image_id": image.id
        }
    ]
)
```

{% endtab %}

{% tab title="JSON Structure" %}

```json
{
  "scenes": [
    {
      "title": "Intro",
      "caption": "Check out this futuristic city!",
      "first_image_description": null,
      "second_image_description": null,
      "first_image_id": "b3e48cbd-7f89-4bd0-a9ad-f2f0afef63a3"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

***

## Next Steps

Now that you know how to generate and retrieve images, let's move on to [Audio Generation (Text-to-Speech)](/api/guides/audio-generation.md). You can create voiceovers or add TTS audio to your automated videos for a more immersive experience.