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-3.0-generate-002).

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.

{
  "images": [
    { "base64": "iVBORw0KGgoAAAANSUhEUg...", "mediaType": "image/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-3.0-generate-002 (default)

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
• 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.