Call a custom image

Custom image deployments do not use the managed /v1 routes. SynapsAI exposes one proxy that authenticates the caller, picks a worker, and forwards the request to your container:

https://api.synapsai.cloud/{model_id}/{path}

Segment	Meaning
`model_id`	Deployment id from Models
`path`	Path your container serves. Omit it to call the container root: `https://api.synapsai.cloud/{model_id}`

The method, query string, and body are forwarded. A successful response is returned with the container’s status code and body. Launch requirements are in Custom image.

Authentication

Use the same Bearer API key as other inference:

Authorization: Bearer $SYNAPSAI_API_KEY

SynapsAI consumes that header. It is not forwarded to the container. Other request headers are forwarded, except Host, Content-Length, Connection, and Transfer-Encoding.

Methods

GET, POST, PUT, PATCH, DELETE, OPTIONS, and HEAD are proxied. The body can be JSON or any other content type your container accepts.

curl -X POST "https://api.synapsai.cloud/$MODEL_ID/v1/chat/completions" \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello"}'

import os
import requests

model_id = os.environ["MODEL_ID"]
response = requests.post(
    f"https://api.synapsai.cloud/{model_id}/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['SYNAPSAI_API_KEY']}"},
    json={"prompt": "Hello"},
    timeout=240,
)
response.raise_for_status()
print(response.json())

The path after the model id is yours. Replace /v1/chat/completions with whatever route the image listens on. Query strings are kept:

https://api.synapsai.cloud/{model_id}/health?verbose=1

Streaming

The proxy streams the container’s response when either of these is true:

Accept includes text/event-stream
The JSON body sets stream to true, or stream_format to sse or audio

curl -N -X POST "https://api.synapsai.cloud/$MODEL_ID/generate" \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello", "stream": true}'

What this route is not

Managed models stay on /v1/.... Sending a managed model id to this proxy returns 400.

Errors

Status	Meaning
`400`	The deployment is not a custom image. Use its `/v1` endpoint instead
`401`	Missing or invalid API key
`404`	The first path segment is a reserved platform route
`429`	Rate limit exceeded. See Rate limits
`502`	The container did not respond
Other `4xx` / `5xx`	The container returned an error. The message is the container’s own error text

Errors use this body. type is APIError when the container or the proxy failed, and HTTPException for a rejected request such as a managed model id.

{
  "error": {
    "type": "APIError",
    "message": "The inference server failed to respond.",
    "code": 502
  }
}

Overview

Models

Custom image

Chat

Completions

Responses

Embeddings

Rerank

Images

Audio

Videos

Classifications

Question answering

Feature extraction

Fill mask

Agents

Vector stores

Model artifacts

Authentication

Methods

Streaming

What this route is not

Errors

​Authentication

​Methods

​Streaming

​What this route is not

​Errors

Authentication

Methods

Streaming

What this route is not

Errors