Images API

Text-to-image and image-to-image/edit; synchronously returns image URLs or Base64 data

The Images API provides text-to-image and image-to-image/edit capabilities. All requests are synchronous and return an image URL or Base64 data on success.

Endpoints

Method	Path	Description
POST	`/v1/images/generations`	Text-to-image
POST	`/v1/images/edits`	Image-to-image / image edit

Prerequisite: model must be a model from the Models API whose supported_endpoint_types includes image-generation.

Billing: Per-request billing. See the usage field in Shared response objects.

POST `/v1/images/generations`

Text-to-image.

Auth: Bearer Token

Content-Type: application/json

Request body

{
  "model": "dall-e-3",
  "prompt": "A white siamese cat sitting on a windowsill, watercolor style",
  "n": 1,
  "size": "1024x1024",
  "quality": "standard",
  "response_format": "url"
}

Request fields

Field	Type	Required	Description
`model`	string	Yes	Image model ID
`prompt`	string	Yes	Image description
`n`	integer	No	Number of images to generate; default 1
`size`	string	No	Size, e.g. `1024x1024`, `1792x1024`
`quality`	string	No	Quality, e.g. `standard`, `hd`
`response_format`	string	No	`url` (default) or `b64_json`
`style`	string	No	Style, e.g. `vivid`, `natural`

Agnes image model example (with reference image):

{
  "model": "agnes-image-2.0-flash",
  "prompt": "A sunset over the ocean, cinematic lighting",
  "size": "1024x768",
  "response_format": "url",
  "extra_body": {
    "response_format": "url"
  },
  "image": ["https://example.com/reference.jpg"]
}

Request example (curl)

curl https://www.guid.ai/v1/images/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "A white siamese cat sitting on a windowsill, watercolor style",
    "n": 1,
    "size": "1024x1024",
    "quality": "standard",
    "response_format": "url"
  }'

Response body

HTTP 200

{
  "created": 1712697600,
  "data": [
    {
      "url": "https://cdn.example.com/generated/image_abc123.png",
      "revised_prompt": "A white Siamese cat perched on a sunlit windowsill, rendered in soft watercolor style."
    }
  ],
  "usage": {
    "quota_type": 1,
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0,
    "request_count": 1,
    "quota": 5000
  }
}

When response_format is b64_json:

{
  "created": 1712697600,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}

Response fields

Field	Type	Description
`created`	integer	Unix timestamp (seconds)
`data`	array	Generation results; length equals request `n`
`data[].url`	string	Image URL (when `response_format=url`)
`data[].b64_json`	string	Base64-encoded image (when `response_format=b64_json`)
`data[].revised_prompt`	string	Prompt rewritten by the model (returned by some models)
`usage`	object	Billing info; see Shared response objects

url and b64_json are mutually exclusive, depending on the request response_format.

Failure response

HTTP 400, etc. Format: Standard errors.

POST `/v1/images/edits`

Image-to-image / image edit.

Auth: Bearer Token

Content-Type: multipart/form-data or application/json (depending on model/channel support)

Request body (multipart/form-data)

Field	Type	Required	Description
`model`	string	Yes	Image model
`prompt`	string	Yes	Edit description
`image`	file	Yes	Image to edit
`mask`	file	No	Mask (for local edits)
`n`	integer	No	Number of images to generate
`size`	string	No	Output size
`response_format`	string	No	`url` or `b64_json`

Request body (JSON; some channels support URL arrays)

{
  "model": "agnes-image-2.0-flash",
  "prompt": "Add a red scarf to the cat",
  "size": "1024x768",
  "image": ["https://example.com/cat.jpg"],
  "response_format": "url"
}

Request example (curl)

JSON (URL array):

curl https://www.guid.ai/v1/images/edits \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-image-2.0-flash",
    "prompt": "Add a red scarf to the cat",
    "size": "1024x768",
    "image": ["https://example.com/cat.jpg"],
    "response_format": "url"
  }'

multipart/form-data (upload a local file):

curl https://www.guid.ai/v1/images/edits \
  -H "Authorization: Bearer sk-xxx" \
  -F "model=dall-e-2" \
  -F "prompt=Add a red scarf to the cat" \
  -F "image=@/path/to/cat.png" \
  -F "response_format=url"

Response body

HTTP 200, same structure as /v1/images/generations:

{
  "created": 1712697600,
  "data": [
    {
      "url": "https://cdn.example.com/generated/edit_abc123.png"
    }
  ]
}

Response fields

Same as POST /v1/images/generations response fields.

Text API

Chat, Legacy Completions, and Responses; supports SSE streaming

Videos API

Create, poll, and download asynchronous video tasks