Getting started with Cloud Image AI

This page covers the shortest path to a generated image: where the key goes, how a service is chosen, and how the picture comes back. For reference images, background edits, and per-provider options, see the user guide.

Prerequisites

Delphi 11 Alexandria or newer (or C++Builder) with TMS AI Studio installed.
A VCL or FMX application with a TTMSMCPCloudImageAI on a form, or created in code.
An account and API key for at least one of the five supported services.

Add TMS.MCP.CloudImageAI to your uses clause, and TMS.MCP.Utils as well — that is where the base64 helper used to decode the result lives.

Set the key and the service

Service chooses the provider and APIKey authenticates against it. Unlike the Cloud AI component, there is one key property, not one per service: it always holds the key of whichever service is currently selected, so the two are changed together.

Value	Service	Default model
`isOpenAI`	OpenAI	`dall-e-2`
`isGemini`	Google Gemini	`gemini-2.5-flash-image`
`isBFL`	Black Forest Labs	`flux-2-flex`
`isStability`	Stability	`sd3.5-flash`
`isReve`	Reve	`reve-create@20250915`

Never assign a key literal in code that gets committed. Read it from the application configuration, an environment variable, or a setup dialog.

Generate an image

Execute sends the request and returns immediately. The image arrives as base64 in OnImageGenerated, and any failure arrives in OnRequestError:

procedure TForm1.SetUpImageAI;
begin
  ImageAI.APIKey := Config.ReadString('imageai', 'openai_key', '');
  ImageAI.Service := isOpenAI;

  { Leave Model empty to take the service default, or name one explicitly. }
  ImageAI.Model := 'gpt-image-1';

  ImageAI.OnImageGenerated := ImageAIImageGenerated;
  ImageAI.OnRequestError := ImageAIRequestError;
end;

procedure TForm1.btnGenerateClick(Sender: TObject);
begin
  if ImageAI.APIKey = '' then
  begin
    { Execute raises 'Please fill in the API Key.' rather than sending an
      unauthenticated request, so check before you call it. }
    memoLog.Lines.Add('No API key configured.');
    Exit;
  end;

  ImageAI.Execute(memoPrompt.Lines.Text);
end;

procedure TForm1.ImageAIImageGenerated(Sender: TObject;
  ARequestResult: TTMSMCPCloudBaseRequestResult; ABase64Image: string);
var
  Stream: TMemoryStream;
begin
  Stream := TMemoryStream.Create;
  try
    TTMSMCPUtils.LoadStreamFromBase64(ABase64Image, Stream);
    Stream.Position := 0;
    imgResult.Bitmap.LoadFromStream(Stream);
  finally
    Stream.Free;
  end;
end;

Execute raises Please fill in the API Key. when APIKey is empty, rather than sending an unauthenticated request — so a missing key surfaces as an exception at the call site, not through the error event.

What comes back

OnImageGenerated carries two things:

Parameter	Contains
`ARequestResult`	The finished HTTP request: `ResponseCode`, `ResultString`, the response headers, and `Success`.
`ABase64Image`	The generated image, base64-encoded.

The image is always base64, on every service. Where a provider answers with a URL instead of image data, the component downloads it and encodes it before the event fires, so one decoding path covers all five: TTMSMCPUtils.LoadStreamFromBase64 fills a stream you then save or load into a picture control.

OnRequestError fires for three different situations — the HTTP call failed, the service rejected the request, or the response arrived successfully but carried no image — so read ResponseCode and ResultString to tell them apart, rather than assuming a network problem.

Requests that take several round trips

Some services answer immediately; others accept the job and hand back a reference to poll. Black Forest Labs always polls, and Stability polls for a background replacement. The component handles this for you: it follows the poll, waits between attempts where the service asks it to, and still fires OnImageGenerated exactly once. The only visible difference is elapsed time and the number of HTTP requests in the log, so do not treat a second OnRequestStarted as a second generation.