Generate Images - Theo API Docs

POST

api

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://www.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

string

Unique image generation ID (prefixed img_).

created

string

ISO 8601 timestamp.

images

object[]

Array of generated images.

Show Image object

url

string | null

Hosted image URL.

engine

string

Theo engine subsystem that produced the image (e.g. "theo-vision").

model

string

Theo model ID (e.g. "theo-1-create").

prompt

string

The prompt used (may include style/ratio enrichment).

usage

object

Show Usage object

cost_cents

number

Cost in cents.

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

Status	Code	Description
400	`missing_prompt`	`prompt` is required
401	`invalid_api_key`	Missing or invalid API key
429	`rate_limit_exceeded`	Too many requests

OpenAI-Compatible Chat Completions

Generate Video

⌘I

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

​Authentication

​Request Body

​Request Examples

​Response

​Example Response

​Errors

Authentication

Request Body

Request Examples

Response

Example Response

Errors