Image Generation (/v1/image)

The Image Generation endpoint allows you to generate images from a text prompt. It works with OpenAI (gpt-image-1, dall-e-3, dall-e-2) and Google (imagen-4.0-generate-001).

Endpoint

• POST /v1/image
• POST /v1/image/{projectId}

If {projectId} is provided in the URL, it takes precedence over the x-project-id header.

Authentication

Requires authentication. See the API Authentication guide.

Headers

• Authorization: Bearer {your-partial-api-key}.{your-token} (Recommended method)
• Content-Type: application/json
• x-project-id: {your-project-id} (Required if projectId is not in the URL path)
• x-ai-key: {your-partial-api-key} (If using non-Bearer token auth methods that require it)
• x-device-token: {your-device-token} (If using legacy device token header auth)

Request Body

{
  "prompt": "A cozy reading nook with plants, soft lighting, and a cat",
  "model": "gpt-image-1",
  "size": "1024x1024",
  "n": 1,
  "seed": 123456,
  "providerOptions": {
    "openai": { "style": "vivid", "quality": "hd" },
    "google": { "safetyFilterLevel": "BLOCK_NONE" }
  }
}

• prompt (string, required): The text description used to generate the image(s).
• model (string, optional): Overrides the project's model. Defaults based on provider.
• size (string, optional): {width}x{height}. Mutually exclusive with aspectRatio.
• aspectRatio (string, optional): {width}:{height}. Mutually exclusive with size.
• n (number, optional): Number of images to generate (default 1, max 20).
• seed (number, optional): If supported by the model, ensures reproducible results.
• maxImagesPerCall (number, optional): Override batching behavior for providers.
• providerOptions (object, optional): Provider-specific options forwarded to the request.

Successful Response (200 OK)

The response includes generated images as base64 strings and optional metadata. If the project has Save images to Vault enabled, each image also includes a signed url and path for the stored file.

{
  "images": [
    {
      "base64": "iVBORw0KGgoAAAANSUhEUg...",
      "mediaType": "image/png",
      "url": "https://...signed-url...",
      "path": "team-id/generated-images/project-id/2025/12/30/uuid.png"
    }
  ],
  "warnings": ["quality parameter not supported"],
  "providerMetadata": { "openai": { "images": [{ "revisedPrompt": "..." }] } }
}

Supported Providers and Default Models

• OpenAI: gpt-image-1 (default), dall-e-3, dall-e-2
• Google AI: imagen-4.0-generate-001 (default), imagen-4.0-fast-generate-001, imagen-4.0-ultra-generate-001

You can specify a custom model in the request body or via project settings.

Error Responses

See the API Errors guide. Common errors:

• UNAUTHORIZED: Authentication failure.
• PROJECT_NOT_FOUND: Invalid project ID.
• BAD_REQUEST: Invalid JSON payload or missing prompt.
• VALIDATION_ERROR: Incompatible parameters (e.g., both size and aspectRatio).
• PROVIDER_ERROR: Underlying provider failed to generate an image.

Example Request (curl)

curl -X POST \
  https://api.proxed.ai/v1/image/{your-project-id} \
  -H "Authorization: Bearer {your-partial-api-key}.{your-device-token-or-test-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Santa Claus driving a Cadillac",
    "model": "gpt-image-1",
    "size": "1024x1024",
    "n": 1
  }'

Pricing

• OpenAI GPT Image 1 (per image):
  • Quality low: 1024x1024 $0.011, 1024x1536 $0.016, 1536x1024 $0.016
  • Quality medium: 1024x1024 $0.042, 1024x1536 $0.063, 1536x1024 $0.063
  • Quality high: 1024x1024 $0.167, 1024x1536 $0.25, 1536x1024 $0.25
• Google Imagen 4 (per image): $0.04
• Google Imagen 4 Fast (per image): $0.02
• OpenAI DALL·E 3 (per image):
  • Standard: 1024x1024 $0.04, 1024x1536 $0.08, 1536x1024 $0.08
  • HD: 1024x1024 $0.08, 1024x1536 $0.12, 1536x1024 $0.12
• OpenAI DALL·E 2 (per image): 1024x1024 $0.016, 1024x1536 $0.018, 1536x1024 $0.02

Notes:

• Costs are recorded per execution when sufficient parameters are provided.