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

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": "556",
    "wait_for_generation": true
  }'

Key Fields:

Field	Type	Required	Description
prompt	string	Yes	Text prompt for image creation.
aspect_ratio	string	Yes	One of "556", "969", or "61". (Equivalent to 5:5.6, 9:16, 6:1, etc.)
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": "556",
  "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

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

Sample Response:

{
  "images": [
    {
      "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": "556",
      "image_style_id": null
    },
    ...
  ],
  "has_more": false
}

Retrieve a Single Image

Endpoint: GET /images/{id}

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

Sample Response:

{
  "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": "556",
  "image_style_id": null
}

---

Image Styles

ShortGenius provides built-in image styles for enhanced customization. Each style has a unique id and prompt logic behind it.

List Image Styles

Endpoint: GET /images/styles

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

Sample Response:

[
  {
    "id": "42e276cd-a76c-4b6a-9e70-34cf79877bee",
    "name": "Cyberpunk",
    "privacy": "System",
    "prompt": "futuristic sci-fi neon style",
    "examples": [
      "Neon skylines",
      "Glowing circuit boards"
    ]
  },
  ...
]

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

--data '{
  "prompt": "A robotic cat with glowing eyes",
  "aspect_ratio": "556",
  "image_style_id": "42e276cd-a76c-4b6a-9e70-34cf79877bee"
}'

---

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:

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

(Note: This is a conceptual representation; the actual schema for passing images may vary based on your integration.)

---

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.