API Endpoints

Complete reference for all AI Gateway API endpoints.

Base URLs

Production: https://ai-gateway.strongly.ai
OpenAI SDK Compatible: /v1/ prefix (e.g., /v1/chat/completions)
Internal API: /api/v1/ prefix (e.g., /api/v1/chat/completions)

Important: The /v1/ and /api/v1/ prefixes are not identical. The /v1/ prefix automatically enables OpenAI SDK compatibility mode, which strips provider and provider_response fields from responses. Use /api/v1/ to get full response data including provider metadata.

Required Headers

Header	Required	Description
`X-User-Id`	Yes	Authenticated user's ID
`X-Organization-ID`	Recommended	Organization ID for multi-tenant resource isolation (required for model CRUD and fine-tuning)
`X-OpenAI-Compat`	Optional	Set to `true` for strict OpenAI SDK compatibility on `/api/v1/` routes
`X-App-Id`	Conditional	App context ID (required for TTS/STT/Generations)
`X-Workflow-Id`	Conditional	Workflow ID (alternative to X-App-Id)
`X-Workspace-Id`	Conditional	Workspace context ID (alternative to X-App-Id)

Note: At least one of X-App-Id, X-Workflow-Id, or X-Workspace-Id must be provided for TTS, STT, and generation endpoints. For chat/completions/embeddings, these are optional and used for analytics tracking.

Models API

List All Models

GET /api/v1/models/

Returns a list of all available models scoped to the organization.

Query Parameters

Parameter	Type	Description
`provider`	string	Filter by provider (e.g., `openai`, `anthropic`)
`model_type`	string	Filter by type (e.g., `chat`, `embedding`, `text_to_speech`)
`capability`	string	Filter by capability (e.g., `vision`, `function_calling`)
`active_only`	boolean	Only show active models (default: `true`)
`owner`	string	Filter by owner user ID
`tags`	string[]	Filter by tags
`skip`	integer	Skip N results (default: 0)
`limit`	integer	Limit to N results (default: 100, max: 1000)

Response

Returns a plain array of model objects (not a paginated wrapper):

[
  {
    "id": "507f1f77bcf86cd799439011",
    "name": "GPT-4o",
    "provider": "openai",
    "model_id": "gpt-4o",
    "model_type": "chat",
    "is_active": true,
    "owner": "user-123",
    "organization_id": "org-456",
    "capabilities": ["streaming", "function_calling", "vision", "json_mode"],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

Note: The id field is the Strongly-generated model ID. Use this value in all API requests (model field in request bodies).

Get Model Details

GET /api/v1/models/{model_id}

Get detailed information about a specific model.

Path Parameters

Parameter	Type	Description
`model_id`	string	Strongly-generated model ID (24-character hex string)

Create Model

POST /api/v1/models/

Create a new model configuration. Requires X-Organization-ID header.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Display name for the model
`provider`	string	Yes	Provider enum value (e.g., `openai`, `anthropic`)
`model_id`	string	Yes	Vendor model ID (e.g., `gpt-4o`)
`model_type`	string	Yes	Model type (e.g., `chat`, `embedding`)
`description`	string	No	Model description

Update Model

PUT /api/v1/models/{model_id}

Update an existing model configuration.

Delete Model

DELETE /api/v1/models/{model_id}

Delete a model configuration. Returns HTTP 204 on success.

List Providers

GET /api/v1/models/providers

Returns a list of supported providers with their capabilities.

Response

Returns an array of provider capability objects:

[
  {
    "name": "openai",
    "display_name": "OpenAI",
    "supported_types": ["chat", "embedding", "text_to_speech", "speech_to_text", "image_generation"],
    "capabilities": ["streaming", "function_calling", "vision", "json_mode"],
    "models": ["gpt-4o", "gpt-4o-mini", "text-embedding-3-large", "dall-e-3"]
  }
]

API Keys

Create API Key

POST /api/v1/models/keys

Create a new API key. The raw key is only returned once in the response.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Name for the API key
`owner`	string	No	Owner user ID (defaults to current user)
`expires_at`	string	No	Expiration date
`allowed_models`	string[]	No	Restrict to specific model IDs
`allowed_ips`	string[]	No	Restrict to specific IP addresses

Response

{
  "id": "key-abc123",
  "name": "My API Key",
  "owner": "user-123",
  "key": "sk-strongly-...",
  "created_at": "2024-01-15T10:30:00Z",
  "is_active": true
}

List API Keys

GET /api/v1/models/keys

List API keys for the current user.

Query Parameters

Parameter	Type	Description
`active_only`	boolean	Only show active keys (default: `true`)
`skip`	integer	Skip N results (default: 0)
`limit`	integer	Limit to N results (default: 100, max: 1000)

Get API Key Details

GET /api/v1/models/keys/{key_id}

Delete API Key

DELETE /api/v1/models/keys/{key_id}

Returns HTTP 204 on success.

Deactivate API Key

POST /api/v1/models/keys/{key_id}/deactivate

Deactivate an API key without deleting it.

Chat Completions

Create Chat Completion

POST /v1/chat/completions

Generate a chat completion response.

Request Body

Field	Type	Required	Description
`model`	string	Yes	Strongly-generated model ID (24-character hex string)
`messages`	array	Yes	Array of message objects
`max_tokens`	integer	No	Maximum tokens to generate
`temperature`	number	No	Sampling temperature (0-2)
`top_p`	number	No	Nucleus sampling parameter
`stream`	boolean	No	Enable streaming response
`tools`	array	No	Available function tools
`tool_choice`	string/object	No	Tool selection preference
`response_format`	object	No	Response format (e.g., `{"type": "json_object"}`)

Message Object

{
  "role": "user|assistant|system|tool",
  "content": "Message content or array of content parts",
  "name": "optional_name",
  "tool_calls": [],
  "tool_call_id": "for_tool_responses"
}

Example Request

curl -X POST https://ai-gateway.strongly.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-User-Id: user-123" \
  -d '{
    "model": "507f1f77bcf86cd799439011",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 1000,
    "temperature": 0.7
  }'

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1706745600,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 10,
    "total_tokens": 30
  }
}

Streaming Response

When stream: true is set, the response is a stream of Server-Sent Events (SSE):

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1706745600,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1706745600,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1706745600,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1706745600,"model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

For models with vision capability, include images in the message content:

{
  "model": "507f1f77bcf86cd799439011",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What's in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/image.png"}}
      ]
    }
  ]
}

Or with base64-encoded images:

{
  "content": [
    {"type": "text", "text": "Describe this image."},
    {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}
  ]
}

Function Calling (Tools)

{
  "model": "507f1f77bcf86cd799439011",
  "messages": [{"role": "user", "content": "What's the weather in Paris?"}],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Text Completions

Create Completion

POST /v1/completions

Generate a text completion (legacy endpoint, prefer chat completions). This endpoint includes guardrail enforcement on both input prompts and output responses.

Request Body

Field	Type	Required	Description
`model`	string	Yes	Strongly-generated model ID (24-character hex string)
`prompt`	string/array	Yes	Input prompt(s)
`max_tokens`	integer	No	Maximum tokens to generate
`temperature`	number	No	Sampling temperature
`stream`	boolean	No	Enable streaming

Embeddings

Create Embeddings

POST /v1/embeddings

Generate vector embeddings for text.

Request Body

Field	Type	Required	Description
`model`	string	Yes	Strongly-generated model ID (24-character hex string)
`input`	string/array	Yes	Text to embed (single or batch)
`encoding_format`	string	No	`float` or `base64`
`dimensions`	integer	No	Desired embedding dimensions (if supported)

Example Request

curl -X POST https://ai-gateway.strongly.ai/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "X-User-Id: user-123" \
  -d '{
    "model": "507f1f77bcf86cd799439014",
    "input": "The quick brown fox jumps over the lazy dog."
  }'

Response

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.0091, 0.0152, ...]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 10,
    "total_tokens": 10
  }
}

Audio - Text-to-Speech (TTS)

Create Speech

POST /v1/audio/speech

Convert text to spoken audio. Requires context headers.

Request Body

Field	Type	Required	Description
`model`	string	Yes	Strongly-generated model ID (24-character hex string)
`input`	string	Yes	Text to convert (max 4096 chars)
`voice`	string	Yes	Voice ID (default: `alloy`)
`response_format`	string	No	`mp3`, `opus`, `aac`, `flac`, `wav`, `pcm` (default: `mp3`)
`speed`	number	No	Speed (0.25 to 4.0, default 1.0)

Available Voices (OpenAI)

alloy - Neutral
echo - Male
fable - Neutral
onyx - Male
nova - Female
shimmer - Female

Example Request

curl -X POST https://ai-gateway.strongly.ai/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "X-User-Id: user-123" \
  -H "X-App-Id: app-456" \
  -d '{
    "model": "507f1f77bcf86cd799439015",
    "input": "Hello, welcome to Strongly AI!",
    "voice": "nova",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Response

Binary audio stream with appropriate Content-Type header and response headers:

Content-Disposition: Filename with format extension
X-Model-Id: Model ID used
X-Voice: Voice used

List TTS Voices

GET /v1/audio/speech/voices

Returns available voices, optionally filtered by provider.

Query Parameters

Parameter	Type	Description
`provider`	string	Filter by provider (e.g., `openai`)

Response

{
  "voices": [
    {
      "id": "alloy",
      "name": "Alloy",
      "provider": "openai",
      "gender": "neutral"
    }
  ]
}

List TTS Models

GET /v1/audio/speech/models

Returns available TTS models for the user.

Audio - Speech-to-Text (STT)

Transcribe Audio

POST /v1/audio/transcriptions

Transcribe audio to text. Requires context headers.

Request Body (multipart/form-data)

Field	Type	Required	Description
`file`	file	Yes	Audio file (mp3, wav, m4a, etc.)
`model`	string	Yes	Strongly-generated model ID (24-character hex string)
`language`	string	No	Language code (ISO-639-1)
`prompt`	string	No	Prompt to guide transcription
`response_format`	string	No	`json`, `text`, `srt`, `vtt`, `verbose_json`
`temperature`	number	No	Sampling temperature (0-1)

Supported Audio Formats

flac, m4a, mp3, mp4, mpeg, mpga, oga, ogg, wav, webm

Maximum File Size: 25MB

Example Request

curl -X POST https://ai-gateway.strongly.ai/v1/audio/transcriptions \
  -H "X-User-Id: user-123" \
  -H "X-App-Id: app-456" \
  -F "file=@audio.mp3" \
  -F "model=507f1f77bcf86cd799439016" \
  -F "response_format=json"

Response

{
  "text": "Hello, this is a test recording.",
  "language": "en",
  "duration": 3.5
}

Translate Audio

POST /v1/audio/translations

Translate audio to English text. Same parameters as transcription (except no language field). Requires context headers.

List STT Models

GET /v1/audio/transcriptions/models

Returns available STT models for the user.

List Supported Languages

GET /v1/audio/transcriptions/languages

Returns languages supported for transcription/translation (20 languages based on OpenAI Whisper).

Generations API

The generations API provides a unified interface for image, video, and music generation. All generation endpoints require context headers (X-App-Id, X-Workflow-Id, or X-Workspace-Id).

Unified Generation

POST /v1/generations

Create any type of generation based on model capabilities. Returns a job ID for async tracking.

Request Body

Field	Type	Required	Description
`model`	string	Yes	Strongly-generated model ID (24-character hex string)
`prompt`	string	Yes	Generation prompt
`type`	string	Yes	`image`, `video`, `music`
`parameters`	object	No	Type-specific parameters

List Generation Jobs

GET /v1/generations

List generation jobs for the user.

Query Parameters

Parameter	Type	Description
`type`	string	Filter by type (`image`, `video`, `music`)
`status`	string	Filter by status
`limit`	integer	Results per page (default: 20)
`offset`	integer	Skip N results (default: 0)

Image Generation

POST /v1/generations/images

Generate images from text prompts. This is a synchronous endpoint that waits for generation to complete.

Request Body

Field	Type	Required	Description
`model`	string	Yes	Strongly-generated model ID (24-character hex string)
`prompt`	string	Yes	Image description
`n`	integer	No	Number of images (1-10)
`size`	string	No	Image dimensions (e.g., `1024x1024`)
`quality`	string	No	`standard` or `hd`
`style`	string	No	`vivid` or `natural`
`response_format`	string	No	`url` or `b64_json`
`negative_prompt`	string	No	What to avoid in generation

Supported Vendor Models

Configure any of these in your account to get a Strongly ID:

OpenAI: DALL-E 3, DALL-E 2
Stability AI: Stable Diffusion 3.5
Black Forest Labs: FLUX 2, FLUX 1
xAI: Grok Aurora

Example Request

curl -X POST https://ai-gateway.strongly.ai/v1/generations/images \
  -H "Content-Type: application/json" \
  -H "X-User-Id: user-123" \
  -H "X-App-Id: app-456" \
  -d '{
    "model": "507f1f77bcf86cd799439017",
    "prompt": "A serene mountain landscape at sunset",
    "size": "1024x1024",
    "quality": "hd"
  }'

Response

{
  "created": 1706745600,
  "data": [
    {
      "url": "https://...",
      "revised_prompt": "A serene mountain landscape..."
    }
  ]
}

Video Generation

POST /v1/generations/videos

Generate videos from text or image prompts. Video generation is asynchronous - returns a job for tracking.

Request Body

Field	Type	Required	Description
`model`	string	Yes	Strongly-generated model ID (24-character hex string)
`prompt`	string	Yes	Video description
`duration`	number	No	Duration in seconds
`resolution`	string	No	Video resolution
`aspect_ratio`	string	No	`16:9`, `9:16`, `1:1`
`style`	string	No	Video style
`fps`	number	No	Frames per second

Supported Vendor Models

Configure any of these in your account to get a Strongly ID:

Runway: Gen-4 Turbo, Gen-3a Turbo
Luma: Ray 2, Ray Flash 2
Google: Veo 2

Response

{
  "job_id": "job-abc123",
  "status": "processing",
  "created": 1706745600,
  "estimated_duration": 30,
  "model": "507f1f77bcf86cd799439018",
  "provider": "runway"
}

Music Generation

POST /v1/generations/music

Generate music from text prompts.

Request Body

Field	Type	Required	Description
`model`	string	Yes	Strongly-generated model ID (24-character hex string)
`prompt`	string	Yes	Music description
`duration`	number	No	Duration in seconds
`instrumental_only`	boolean	No	Generate instrumental only
`lyrics`	string	No	Lyrics for vocal tracks
`genre`	string	No	Musical genre
`mood`	string	No	Musical mood
`tempo`	number	No	BPM
`intensity`	number	No	Intensity level
`format`	string	No	Output audio format

Supported Vendor Models

Configure any of these in your account to get a Strongly ID:

ElevenLabs: Music v1

Get Generation Job Status

GET /v1/generations/{job_id}

Get the status of a generation job.

Cancel Generation Job

DELETE /v1/generations/{job_id}

Cancel a generation job if it is still queued.

List Generation Models

GET /v1/generations/models

List available generation models, optionally filtered by type.

Query Parameters

Parameter	Type	Description
`type`	string	Filter by type (`image`, `video`, `music`)

Get Provider Operation Status

GET /v1/generations/models/{model_id}/operations/{operation_id}

Check the status of an async generation operation at the provider level (e.g., Google Veo).

Path Parameters

Parameter	Type	Description
`model_id`	string	Strongly-generated model ID (24-character hex string)
`operation_id`	string	Provider-specific operation/job ID

Response

{
  "job_id": "operation-abc123",
  "status": "completed",
  "progress": 100,
  "url": "https://...",
  "model": "507f1f77bcf86cd799439018",
  "provider": "google"
}

Status Values: pending, processing, completed, failed

Health Check

API Health

GET /api/v1/health

Returns health status of the gateway.

Simple Health Check

GET /healthcheck

Returns simple health status for load balancer checks.

Error Responses

All errors follow a standard format:

{
  "detail": "Detailed error message"
}

For structured error types:

{
  "detail": {
    "message": "X-User-Id header is required",
    "error_code": "missing_user_id"
  }
}

Error Types

Type	HTTP Status	Description
`missing_user_id`	401	X-User-Id header not provided
`invalid_api_key`	401	Invalid authentication
`model_not_found`	404	Requested model doesn't exist
`validation_error`	400	Invalid request parameters or missing context headers
`rate_limit_exceeded`	429	Too many requests
`content_filter`	400	Content blocked by guardrails
`provider_error`	502	Upstream provider error
`provider_unavailable`	503	Provider temporarily unavailable
`internal_error`	500	Internal server error

Rate Limits

Rate limiting is configurable per deployment via the RATE_LIMIT_PER_MINUTE and ENABLE_RATE_LIMITING settings. When enabled, rate limits are applied per user per endpoint.

When rate limited, the response includes:

{
  "detail": "Rate limit exceeded. Retry after 30 seconds."
}

Headers included on all rate-limited responses:

X-RateLimit-Remaining: Remaining requests in current window
X-RateLimit-Reset: Seconds until the rate limit resets
Retry-After: Seconds to wait before retrying (on 429 responses)

Pagination

The Models API uses skip/limit pagination:

Parameter	Type	Default	Description
`skip`	integer	0	Number of results to skip
`limit`	integer	100	Items per page (max 1000)

The response is a plain array of results. Use skip and limit to paginate through large result sets.

Base URLs​

Required Headers​

Models API​

List All Models​

Get Model Details​

Create Model​

Update Model​

Delete Model​

List Providers​

API Keys​

Create API Key​

List API Keys​

Get API Key Details​

Delete API Key​

Deactivate API Key​

Chat Completions​

Create Chat Completion​

Streaming Response​

Vision (Multi-Modal)​

Function Calling (Tools)​

Text Completions​

Create Completion​

Embeddings​

Create Embeddings​

Audio - Text-to-Speech (TTS)​

Create Speech​

List TTS Voices​

List TTS Models​

Audio - Speech-to-Text (STT)​

Transcribe Audio​

Translate Audio​

List STT Models​

List Supported Languages​

Generations API​

Unified Generation​

List Generation Jobs​

Image Generation​

Video Generation​

Music Generation​

Get Generation Job Status​

Cancel Generation Job​

List Generation Models​

Get Provider Operation Status​

Health Check​

API Health​

Simple Health Check​

Error Responses​

Error Types​

Rate Limits​

Pagination​

Base URLs

Required Headers

Models API

List All Models

Get Model Details

Create Model

Update Model

Delete Model

List Providers

API Keys

Create API Key

List API Keys

Get API Key Details

Delete API Key

Deactivate API Key

Chat Completions

Create Chat Completion

Streaming Response

Vision (Multi-Modal)

Function Calling (Tools)

Text Completions

Create Completion

Embeddings

Create Embeddings

Audio - Text-to-Speech (TTS)

Create Speech

List TTS Voices

List TTS Models

Audio - Speech-to-Text (STT)

Transcribe Audio

Translate Audio

List STT Models

List Supported Languages

Generations API

Unified Generation

List Generation Jobs

Image Generation

Video Generation

Music Generation

Get Generation Job Status

Cancel Generation Job

List Generation Models

Get Provider Operation Status

Health Check

API Health

Simple Health Check

Error Responses

Error Types

Rate Limits

Pagination