Generate or Edit Images

curl --request POST \
  --url https://secureai.hiperai.ai/api/external/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'prompt=A beautiful sunset over the ocean with mountains in the background, digital art style' \
  --form image=@example-file \
  --form smltp_policy=internal \
  --form response_format=url \
  --form size=1024x1024 \
  --form n=1

import requests

url = "https://secureai.hiperai.ai/api/external/images/generations"

files = { "image": ("example-file", open("example-file", "rb")) }
payload = {
    "prompt": "A beautiful sunset over the ocean with mountains in the background, digital art style",
    "smltp_policy": "internal",
    "response_format": "url",
    "size": "1024x1024",
    "n": "1"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('prompt', 'A beautiful sunset over the ocean with mountains in the background, digital art style');
form.append('image', '<string>');
form.append('smltp_policy', 'internal');
form.append('response_format', 'url');
form.append('size', '1024x1024');
form.append('n', '1');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://secureai.hiperai.ai/api/external/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "id": "90d3756f-41c3-4f86-a18d-e257bfbc33a3",
  "object": "image.generation",
  "created": 1705312200,
  "data": [
    {
      "url": "http://localhost:5173/uploads/secureai_image_api_68c5c6d2d57c85b102eb05e2_90d3756f_0.png",
      "revised_prompt": "A beautiful sunset over the ocean with mountains in the background, digital art style"
    }
  ],
  "metadata": {
    "model": "google/gemini-2.5-flash-image-preview",
    "provider": "Google",
    "total_images": 1,
    "is_image_to_image": false,
    "text_response": null,
    "smltp_trace_id": "trx-220eca66-5e3a-4a72-886b-e6ba8cde18a6",
    "smltp_bundle_id": "jti-bb850e61-fbfe-412a-8b0d-d180d4a36d22",
    "smltp_policy": "internal"
  }
}

{
  "success": false,
  "error": "Invalid prompt",
  "message": "Prompt is required and must be a non-empty string",
  "request_id": "90d3756f-41c3-4f86-a18d-e257bfbc33a3"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "File too large",
  "message": "Maximum image size is 10MB",
  "request_id": "90d3756f-41c3-4f86-a18d-e257bfbc33a3"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "Service unavailable",
  "message": "Image generation service is not configured",
  "request_id": "90d3756f-41c3-4f86-a18d-e257bfbc33a3"
}

Modelos & Geração de IA

Geração de Imagens

Generate new images from text prompts or transform existing images using Google Gemini 2.5 Flash Image. All requests and responses are processed through SMLTP for security and compliance.

This endpoint supports:

Text-to-Image: Generate images from text descriptions
Image-to-Image: Transform or edit existing images (upload an image file)

All prompts and responses are automatically processed through SMLTP for audit logging and compliance.

POST

images

generations

Generate or Edit Images

curl --request POST \
  --url https://secureai.hiperai.ai/api/external/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'prompt=A beautiful sunset over the ocean with mountains in the background, digital art style' \
  --form image=@example-file \
  --form smltp_policy=internal \
  --form response_format=url \
  --form size=1024x1024 \
  --form n=1

import requests

url = "https://secureai.hiperai.ai/api/external/images/generations"

files = { "image": ("example-file", open("example-file", "rb")) }
payload = {
    "prompt": "A beautiful sunset over the ocean with mountains in the background, digital art style",
    "smltp_policy": "internal",
    "response_format": "url",
    "size": "1024x1024",
    "n": "1"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('prompt', 'A beautiful sunset over the ocean with mountains in the background, digital art style');
form.append('image', '<string>');
form.append('smltp_policy', 'internal');
form.append('response_format', 'url');
form.append('size', '1024x1024');
form.append('n', '1');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://secureai.hiperai.ai/api/external/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "id": "90d3756f-41c3-4f86-a18d-e257bfbc33a3",
  "object": "image.generation",
  "created": 1705312200,
  "data": [
    {
      "url": "http://localhost:5173/uploads/secureai_image_api_68c5c6d2d57c85b102eb05e2_90d3756f_0.png",
      "revised_prompt": "A beautiful sunset over the ocean with mountains in the background, digital art style"
    }
  ],
  "metadata": {
    "model": "google/gemini-2.5-flash-image-preview",
    "provider": "Google",
    "total_images": 1,
    "is_image_to_image": false,
    "text_response": null,
    "smltp_trace_id": "trx-220eca66-5e3a-4a72-886b-e6ba8cde18a6",
    "smltp_bundle_id": "jti-bb850e61-fbfe-412a-8b0d-d180d4a36d22",
    "smltp_policy": "internal"
  }
}

{
  "success": false,
  "error": "Invalid prompt",
  "message": "Prompt is required and must be a non-empty string",
  "request_id": "90d3756f-41c3-4f86-a18d-e257bfbc33a3"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "File too large",
  "message": "Maximum image size is 10MB",
  "request_id": "90d3756f-41c3-4f86-a18d-e257bfbc33a3"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "Service unavailable",
  "message": "Image generation service is not configured",
  "request_id": "90d3756f-41c3-4f86-a18d-e257bfbc33a3"
}

Gerar imagens

Gere novas imagens a partir de prompts de texto ou transforme imagens existentes usando o Google Gemini 2.5 Flash Image.

Ponto final

POST /images/generations

Descrição

Gere novas imagens a partir de descrições de texto ou transforme imagens existentes. Este ponto de extremidade suporta:

Text-to-Image: Gere imagens a partir de descrições de texto
Image-to-Image: Transforme ou edite imagens existentes (faça upload de um arquivo de imagem)

Todos os prompts e respostas são processados automaticamente por meio do SMLTP para registro de auditoria e conformidade.

Autenticação

Obrigatório: Chave API

Authorization: Bearer sk-your-api-key-here

Corpo da solicitação

Este endpoint aceita os formatos multipart/form-data (para uploads de arquivos) e application/json.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`prompt`	corda	Sim	Prompt de texto descrevendo a imagem a ser gerada ou como transformar a imagem enviada (1-4000 caracteres)
`image`	binário	Não	Arquivo de imagem para geração de imagem para imagem (JPEG, PNG, WEBP ou GIF, máximo de 10 MB)
`smltp_policy`	corda	Não	Política de segurança SMLTP (padrão: “interno”)
`response_format`	corda	Não	Formato de resposta: “url” ou “b64_json” (padrão: “url”)
`size`	corda	Não	Tamanho da imagem (padrão: “1024x1024”)
`n`	inteiro	Não	Número de imagens a serem geradas (1-4, padrão: 1)

Exemplos de solicitação

Texto para imagem (JSON)

curl -X POST "https://{customer.name}.hiperai.ai/api/external/images/generations" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful sunset over the ocean with mountains in the background, digital art style",
    "smltp_policy": "internal",
    "response_format": "url",
    "n": 1
  }'

Imagem para imagem (dados de formulário multipartes)

curl -X POST "https://{customer.name}.hiperai.ai/api/external/images/generations" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -F "prompt=Add dramatic sunset colors to the sky" \
  -F "image=@/path/to/image.jpg" \
  -F "smltp_policy=internal" \
  -F "response_format=url"

###JavaScript/Node.js

// Text-to-Image
const response = await fetch('https://{customer.name}.hiperai.ai/api/external/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'A beautiful sunset over the ocean with mountains in the background, digital art style',
    smltp_policy: 'internal',
    response_format: 'url',
    n: 1
  })
});

const data = await response.json();
console.log('Generated image URL:', data.data[0].url);

// Image-to-Image
const formData = new FormData();
formData.append('prompt', 'Add dramatic sunset colors to the sky');
formData.append('image', fileInput.files[0]);
formData.append('smltp_policy', 'internal');
formData.append('response_format', 'url');

const response2 = await fetch('https://{customer.name}.hiperai.ai/api/external/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-your-api-key-here'
  },
  body: formData
});

const data2 = await response2.json();
console.log('Edited image URL:', data2.data[0].url);

###Píton

import requests

# Text-to-Image
url = "https://{customer.name}.hiperai.ai/api/external/images/generations"
headers = {
    "Authorization": "Bearer sk-your-api-key-here",
    "Content-Type": "application/json"
}
data = {
    "prompt": "A beautiful sunset over the ocean with mountains in the background, digital art style",
    "smltp_policy": "internal",
    "response_format": "url",
    "n": 1
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print('Generated image URL:', result['data'][0]['url'])

# Image-to-Image
with open('image.jpg', 'rb') as f:
    files = {'image': f}
    data = {
        'prompt': 'Add dramatic sunset colors to the sky',
        'smltp_policy': 'internal',
        'response_format': 'url'
    }
    response = requests.post(url, headers={'Authorization': 'Bearer sk-your-api-key-here'}, files=files, data=data)
    result = response.json()
    print('Edited image URL:', result['data'][0]['url'])

Resposta

Resposta de sucesso (200)

{
  "success": true,
  "id": "90d3756f-41c3-4f86-a18d-e257bfbc33a3",
  "object": "image.generation",
  "created": 1705312200,
  "data": [
    {
      "url": "http://localhost:5173/uploads/secureai_image_api_68c5c6d2d57c85b102eb05e2_90d3756f_0.png",
      "revised_prompt": "A beautiful sunset over the ocean with mountains in the background, digital art style"
    }
  ],
  "metadata": {
    "model": "google/gemini-2.5-flash-image-preview",
    "provider": "Google",
    "total_images": 1,
    "is_image_to_image": false,
    "text_response": null,
    "smltp_trace_id": "trx-220eca66-5e3a-4a72-886b-e6ba8cde18a6",
    "smltp_bundle_id": "jti-bb850e61-fbfe-412a-8b0d-d180d4a36d22",
    "smltp_policy": "internal"
  }
}

Campos de resposta

Campo	Tipo	Descrição
`success`	booleano	Sempre verdadeiro para solicitações bem-sucedidas
`id`	corda	Identificador único do pedido
`object`	corda	Tipo de objeto: “image.generação”
`created`	inteiro	Carimbo de data e hora Unix de quando as imagens foram criadas
`data`	matriz	Matriz de imagens geradas
`metadata`	objeto	Metadados adicionais, incluindo rastreamento SMLTP

Objeto de imagem

Campo	Tipo	Descrição
`url`	corda	URL para acessar a imagem gerada (quando response_format for “url”)
`b64_json`	corda	Dados de imagem codificados em Base64 (quando response_format é “b64_json”)
`revised_prompt`	corda	O prompt realmente usado para geração (pode ser diferente da entrada)

Objeto de metadados

Campo	Tipo	Descrição
`model`	corda	Modelo usado: “google/gemini-2.5-flash-image-preview”
`provider`	corda	Provedor: “Google”
`total_images`	inteiro	Número total de imagens geradas
`is_image_to_image`	booleano	Se esta foi uma geração imagem a imagem
`text_response`	string\|nulo	Resposta de texto opcional do modelo
`smltp_trace_id`	corda	SMLTP ID de rastreamento para rastreamento de auditoria
`smltp_bundle_id`	corda	ID do pacote SMLTP para rastreamento de auditoria
`smltp_policy`	corda	Política SMLTP que foi aplicada

Respostas de erro

400 Solicitação incorreta

{
  "success": false,
  "error": "Invalid prompt",
  "message": "Prompt is required and must be a non-empty string",
  "request_id": "90d3756f-41c3-4f86-a18d-e257bfbc33a3"
}

401 Não autorizado

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked"
}

403 Proibido

{
  "success": false,
  "error": "Access denied",
  "message": "SMLTP policy not allowed"
}

413 Carga útil muito grande

{
  "success": false,
  "error": "File too large",
  "message": "Maximum image size is 10MB",
  "request_id": "90d3756f-41c3-4f86-a18d-e257bfbc33a3"
}

500 Erro interno do servidor

{
  "success": false,
  "error": "Internal server error",
  "message": "Image generation failed"
}

503 Serviço indisponível

{
  "success": false,
  "error": "Service unavailable",
  "message": "Image generation service is not configured",
  "request_id": "90d3756f-41c3-4f86-a18d-e257bfbc33a3"
}

Notas

Formatos de imagem suportados para upload: JPEG, PNG, WEBP, GIF
Tamanho máximo do arquivo: 10 MB por imagem
Ao fazer upload de uma imagem, o prompt descreve como transformá-la
Gemini normalmente gera de 1 a 4 imagens por solicitação
Todas as solicitações são processadas através de SMLTP para segurança e conformidade
Use response_format: "b64_json" para receber dados de imagem codificados em base64 em vez de URLs

Autorizações

Authorization

string

header

obrigatório

API key authentication using Bearer token format. Example: Authorization: Bearer sk-your-api-key-here

Corpo

prompt

string

obrigatório

The text prompt describing the image to generate or how to transform the uploaded image

Required string length: 1 - 4000

Exemplo:

"A beautiful sunset over the ocean with mountains in the background, digital art style"

image

file

Optional image file for image-to-image generation (JPEG, PNG, WEBP, or GIF, max 10MB)

smltp_policy

string

padrão:internal

SMLTP security policy to apply (e.g., 'internal', 'public', 'confidential', 'hipaa', 'gdpr')

Exemplo:

"internal"

response_format

enum<string>

padrão:url

The format of the response images

Opções disponíveis:

url,

b64_json

Exemplo:

"url"

size

string

padrão:1024x1024

The size of the generated images (for future use, currently uses default size)

Exemplo:

"1024x1024"

integer

padrão:1

Number of images to generate (Gemini typically generates 1-4 images)

Intervalo necessário: 1 <= x <= 4

Exemplo:

1

Resposta

Images generated successfully

success

boolean

Exemplo:

true

string

Unique request identifier

Exemplo:

"90d3756f-41c3-4f86-a18d-e257bfbc33a3"

object

string

Exemplo:

"image.generation"

created

integer

Unix timestamp of when the images were created

Exemplo:

1705312200

data

object[]

Array of generated images

Show child attributes

metadata

object

Show child attributes

Primeiros Passos & Configuração

Modelos & Geração de IA

Knowledge Base & RAG

Segurança, Guardrails & Auditoria

Usuários & Acesso (IAM)

Faturamento, Cotas & Webhooks

Geração de Imagens

Gerar imagens

Ponto final

Descrição

Autenticação

Corpo da solicitação

Parâmetros

Exemplos de solicitação

Texto para imagem (JSON)

Imagem para imagem (dados de formulário multipartes)

Resposta

Resposta de sucesso (200)

Campos de resposta

Objeto de imagem

Objeto de metadados

Respostas de erro

400 Solicitação incorreta

401 Não autorizado

403 Proibido

413 Carga útil muito grande

500 Erro interno do servidor

503 Serviço indisponível

Notas

Autorizações

Corpo

Resposta

​Gerar imagens

​Ponto final

​Descrição

​Autenticação

​Corpo da solicitação

​Parâmetros

​Exemplos de solicitação

​Texto para imagem (JSON)

​Imagem para imagem (dados de formulário multipartes)

​Resposta

​Resposta de sucesso (200)

​Campos de resposta

​Objeto de imagem

​Objeto de metadados

​Respostas de erro

​400 Solicitação incorreta

​401 Não autorizado

​403 Proibido

​413 Carga útil muito grande

​500 Erro interno do servidor

​503 Serviço indisponível

​Notas

Autorizações

Corpo

Resposta

Gerar imagens

Ponto final

Descrição

Autenticação

Corpo da solicitação

Parâmetros

Exemplos de solicitação

Texto para imagem (JSON)

Imagem para imagem (dados de formulário multipartes)

Resposta

Resposta de sucesso (200)

Campos de resposta

Objeto de imagem

Objeto de metadados

Respostas de erro

400 Solicitação incorreta

401 Não autorizado

403 Proibido

413 Carga útil muito grande

500 Erro interno do servidor

503 Serviço indisponível

Notas