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

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}`)

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}")

cURL

curl --request POST \
  --url "https://shortgenius.com/api/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
  }'

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:

{
  "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

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}`)
}

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}")

cURL

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

Retrieve a Single Image

Endpoint: GET /images/{id}

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}`)

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}")

cURL

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

---

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

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(', ')}`)
}

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)}")

cURL

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

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

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
})

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
)

cURL

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

---

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:

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
    }
  ]
})

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
        }
    ]
)

JSON Structure

{
  "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"
    }
  ]
}

---

Next Steps

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