Skip to main content
POST
/
api
/
v1
/
images
Generate Images
curl --request POST \
  --url https://api.example.com/api/v1/images \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "style": "<string>",
  "aspect_ratio": "<string>",
  "count": 123
}
'
{
  "id": "<string>",
  "created": "<string>",
  "images": [
    {
      "url": {},
      "engine": "<string>",
      "model": "<string>",
      "prompt": "<string>"
    }
  ],
  "usage": {
    "cost_cents": 123
  }
}
Generate one or more images from a text prompt. This is a synchronous endpoint — images are returned directly in the response.

​
Authentication

Requires a Bearer token. See Authentication.

​
Request Body

​
prompt
string
required
Text description of the image(s) to generate.
​
style
string
Visual style hint (e.g., "photorealistic", "illustration", "watercolor", "3d-render"). Appended to the prompt for the image engine.
​
aspect_ratio
string
Aspect ratio (e.g., "1:1", "16:9", "9:16", "4:3"). Defaults to the engine’s native ratio.
​
count
integer
default:"1"
Number of images to generate (1–4).

​
Request Examples

curl -X POST https://hitheo.ai/api/v1/images \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A minimalist tech logo, blue and white",
    "style": "photorealistic",
    "aspect_ratio": "1:1",
    "count": 2
  }'

​
Response

​
id
string
Unique image generation ID (prefixed img_).
​
created
string
ISO 8601 timestamp.
​
images
object[]
Array of generated images.
​
usage
object

​
Example Response

{
  "id": "img_abc123",
  "created": "2026-04-10T12:00:00Z",
  "images": [
    {
      "url": "https://artifacts.hitheo.ai/img/abc123-1.png",
      "engine": "theo-vision",
      "model": "theo-1-create",
      "prompt": "A minimalist tech logo, blue and white Style: photorealistic. Aspect ratio: 1:1."
    },
    {
      "url": "https://artifacts.hitheo.ai/img/abc123-2.png",
      "engine": "theo-vision",
      "model": "theo-1-create",
      "prompt": "A minimalist tech logo, blue and white Style: photorealistic. Aspect ratio: 1:1."
    }
  ],
  "usage": { "cost_cents": 0.08 }
}

​
Errors

StatusCodeDescription
400missing_promptprompt is required
401invalid_api_keyMissing or invalid API key
429rate_limit_exceededToo many requests