Images API

The /images/generate endpoint creates images from text prompts using AI models.

Quick Reference

POST /api/v1/images/generate

Generate images from a text description.

Generate Images

POST /api/v1/images/generate

Authentication

Requires either:

  • Secret key (mr_sk_*): Backend use with full project access
  • Customer bearer token: Customer scoped token for data-plane access

Publishable keys (mr_pk_*) cannot call this endpoint directly.

Request Body

Field Type Required Description
model string No* Image generation model ID (e.g., gemini-2.5-flash-image)
prompt string Yes Text description of the image to generate
response_format string No Output format: url (default) or b64_json

*Model is optional when using a customer token with a tier that defines a default model.

Response Formats

Format Description Use Case
url Returns hosted image URLs Production (requires storage configuration)
b64_json Returns base64-encoded image data Testing/development (no storage needed)

Response

{
  "id": "img_abc123",
  "model": "gemini-2.5-flash-image",
  "data": [
    {
      "url": "https://storage.example.com/images/abc123.png",
      "mime_type": "image/png"
    }
  ],
  "usage": {
    "images": 1
  }
}

Response Fields

Field Type Description
id string Unique identifier for this generation request
model string Model used for generation
data array Array of generated images
usage object Usage statistics

ImageData Object

Field Type Description
url string URL of the generated image (when response_format is url)
b64_json string Base64-encoded image data (when response_format is b64_json)
mime_type string MIME type of the image (e.g., image/png, image/webp)

Usage Object

Field Type Description
images integer Number of images generated

SDK Examples

import { ModelRelay } from "@modelrelay/sdk";

const mr = ModelRelay.fromSecretKey(process.env.MODELRELAY_API_KEY!);

// Production use (default) - returns URLs
const response = await mr.images.generate({
  model: "gemini-2.5-flash-image",
  prompt: "A futuristic cityscape at sunset",
});

console.log(response.data[0].url);
console.log(response.data[0].mime_type);

// Testing/development - returns base64
const testResponse = await mr.images.generate({
  model: "gemini-2.5-flash-image",
  prompt: "A futuristic cityscape at sunset",
  response_format: "b64_json",
});

// Decode base64 to use the image
const imageData = testResponse.data[0].b64_json;

import sdk "github.com/modelrelay/sdk-go"

client, _ := sdk.NewClientFromSecretKey(os.Getenv("MODELRELAY_API_KEY"))

// Production use (default) - returns URLs
resp, _ := client.Images.Generate(ctx, sdk.ImageRequest{
    Model:  "gemini-2.5-flash-image",
    Prompt: "A futuristic cityscape at sunset",
})

fmt.Println(*resp.Data[0].Url)
fmt.Println(*resp.Data[0].MimeType)

// Testing/development - returns base64
format := sdk.ImageResponseFormatB64JSON
testResp, _ := client.Images.Generate(ctx, sdk.ImageRequest{
    Model:          "gemini-2.5-flash-image",
    Prompt:         "A futuristic cityscape at sunset",
    ResponseFormat: &format,
})

imageData := *testResp.Data[0].B64Json

use modelrelay::{Client, ImageRequest, ImageResponseFormat};

let client = Client::from_secret_key(std::env::var("MODELRELAY_API_KEY")?)?
    .build()?;

// Production use (default) - returns URLs
let response = client.images().generate(ImageRequest {
    model: "gemini-2.5-flash-image".into(),
    prompt: "A futuristic cityscape at sunset".into(),
    response_format: None,
}).await?;

println!("{}", response.data[0].url.as_deref().unwrap_or_default());
println!("{}", response.data[0].mime_type.as_deref().unwrap_or_default());

// Testing/development - returns base64
let test_response = client.images().generate(ImageRequest {
    model: "gemini-2.5-flash-image".into(),
    prompt: "A futuristic cityscape at sunset".into(),
    response_format: Some(ImageResponseFormat::B64Json),
}).await?;

let image_data = test_response.data[0].b64_json.as_deref().unwrap_or_default();

Error Responses

Storage Not Configured

When using response_format: "url" without storage configuration:

{
  "error": {
    "code": "invalid_input",
    "message": "response_format 'url' requires image storage. Use 'b64_json' for testing, or configure storage for production use."
  }
}

Missing Required Fields

{
  "error": {
    "code": "invalid_input",
    "message": "model is required"
  }
}

Tier-Based Model Selection

When using a customer bearer token, the model can be omitted if the customer’s tier defines a default model:

// Customer token auth - tier provides the model
const mr = new ModelRelay({ token: customerBearerToken });

const response = await mr.images.generate({
  prompt: "A futuristic cityscape at sunset",
  // model omitted - uses tier default
});

This matches the behavior of the /responses endpoint.

Notes

  • The default response_format is url, which requires storage configuration on the server
  • Use b64_json for testing and development without storage setup
  • Image generation models vary in supported output formats and sizes
  • Usage is tracked and billed per image generated
  • When using a customer token with a tier, the tier’s default model is used if no model is specified

Next Steps