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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://shortgenius.gitbook.io/api/guides/image-generation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.