API reference

OttoPort is a unified gateway that routes LLM, image, and video generation through a single OpenAI-compatible surface. Every request is authenticated with one key and billed against one credit balance — no per-provider accounts to juggle.

• Chat is synchronous. Responses stream token-by-token, exactly like the OpenAI API.
• Image & video wait on the queue. The gateway holds the request until the provider finishes and returns the result URL.
• One catalog. Discover every model, its provider, and its price at GET /v1/models.

Install the OpenAI SDK, set base_url to the OttoPort gateway, and use your op- key as the API key. Your first chat request is three lines away.

pip install openai      # or: npm install openai

curl https://ottoport.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OTTOPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'

The same client works for images and video — switch the model id and call images.generate or the videos endpoint. See the sections below.

Every request must include an Authorization header with your secret key. Keys are prefixed with op- and are created in API Keys. Keep them server-side — never ship a key in client code.

Authorization: Bearer op-xxxxxxxxxxxxxxxxxxxxxxxx

OpenAI-compatible chat across GPT, Claude, and Gemini. Streaming, tool use, and function calling work unchanged — OttoPort translates between the OpenAI schema and each provider.

curl https://ottoport.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OTTOPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      { "role": "system", "content": "You are concise." },
      { "role": "user", "content": "Explain MCP in one line." }
    ],
    "temperature": 0.7,
    "stream": false
  }'

Response

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 24, "completion_tokens": 18, "total_tokens": 42 }
}

Generate or edit images with GPT Image and Nano Banana models. Pass image_url to run image-to-image edits. The gateway waits for the provider and returns hosted URLs.

The same endpoint serves layer decomposition. qwen-image-layered and seedream-5.0-layers take one image_url and return one data entry per RGBA layer, bottom of the stack first, each with a layer object — its index, and on Seedream its name, z-order and bounding box. The prompt is an optional caption there, and you are billed per layer returned.

curl https://ottoport.ai/api/v1/images/generations \
  -H "Authorization: Bearer $OTTOPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "a chrome torus on a black background, studio light",
    "size": "1024x1024",
    "n": 1
  }'

Response

{
  "created": 1736200000,
  "model": "nano-banana-pro",
  "data": [{ "url": "https://cdn.ottoport.ai/images/9f2a...png", "expires_at": "2026-01-14T00:00:00.000Z" }],
  "usage": { "cost": 0.24 }
}

Generate video with Veo, Kling, and Seedance. Video takes minutes, so the request does not wait: it places a hold on your balance for the quoted price, queues the job and answers 202 with a job whose status is queued. Follow it by polling GET /v1/videos/generations/:id or, better, by registering a webhook. A finished job is completed with the result URLs, or failed with an error and the hold released. Files hosted by OttoPort carry expires_at; download them within three days.

The same endpoint serves depth estimation. video-depth-anything takes one video_url and nothing else — no prompt — and returns a grayscale depth video of the same length and size. It is billed per second of the source, which the gateway measures.

Every submission needs an Idempotency-Key header, a unique string of up to 255 characters such as a UUID. The key is tied to its request body, so reusing it with a different body returns 409 idempotency_key_reused.

curl https://ottoport.ai/api/v1/videos/generations \
  -H "Authorization: Bearer $OTTOPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "kling-3.0",
    "prompt": "cinematic product reveal, slow dolly, black background",
    "duration": 5,
    "aspect_ratio": "16:9",
    "webhook_url": "https://example.com/hooks/ottoport",
    "webhook_secret": "'"$OTTOPORT_WEBHOOK_SECRET"'"
  }'

# Without a webhook, poll until status is completed or failed:
curl https://ottoport.ai/api/v1/videos/generations/$JOB_ID \
  -H "Authorization: Bearer $OTTOPORT_API_KEY"

Response

// 202 Accepted
{
  "id": "7c1e9a52-...",
  "job_id": "7c1e9a52-...",
  "model": "kling-3.0",
  "status": "queued",
  "created": 1736200000,
  "updated": "2026-01-11T00:00:00.000Z"
}

// GET /v1/videos/generations/7c1e9a52-... once finished
{
  "id": "7c1e9a52-...",
  "status": "completed",
  "data": [{ "url": "https://cdn.ottoport.ai/videos/7c1e....mp4", "expires_at": "2026-01-14T00:00:00.000Z" }],
  "webhook": {
    "url": "https://example.com/hooks/ottoport",
    "deliveries": [{ "event": "video.completed", "status": "delivered", "attempts": 1, "max_attempts": 5, "response_status": 200 }]
  }
}

Pass webhook_url and webhook_secret when you submit a video, or an image with async, and OttoPort POSTs the finished job to that URL instead of making you poll. Webhooks are registered per job; there is nothing to set up in the dashboard.

Events

Each delivery is a JSON POST whose body is { event, data }, where data is the same job object GET /v1/videos/generations/:id returns.

POST /hooks/ottoport HTTP/1.1
content-type: application/json
user-agent: OttoPort-Webhooks/1.0
x-ottoport-event: video.completed
x-ottoport-delivery: 3f0b8d4e-...
x-ottoport-signature: t=1736200123,v1=5d2c0b...

{
  "event": "video.completed",
  "data": {
    "id": "7c1e9a52-...",
    "job_id": "7c1e9a52-...",
    "model": "kling-3.0",
    "status": "completed",
    "created": 1736200000,
    "updated": "2026-01-11T00:02:03.000Z",
    "data": [{ "url": "https://cdn.ottoport.ai/videos/7c1e....mp4", "expires_at": "2026-01-14T00:02:03.000Z" }]
  }
}

Verify the signature

x-ottoport-signature is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of `${t}.${raw body}` keyed with your webhook_secret. Compute it over the raw request body, since re-serialized JSON will not match. Compare in constant time, and reject timestamps more than five minutes old to stop replays.

# Recompute the signature by hand for a saved delivery body:
TS=1736200123
printf '%s.%s' "$TS" "$(cat body.json)" \
  | openssl dgst -sha256 -hmac "$OTTOPORT_WEBHOOK_SECRET" -hex
# Compare the digest with v1= in x-ottoport-signature.

Delivery and retries

A delivery succeeds when your endpoint answers 2xx within 10 seconds. Any other status, a timeout, a connection error or a redirect counts as a failed attempt; redirects are not followed, so point webhook_url at the final address. Failed deliveries are retried with increasing delays, 1, 5, 30 and 120 minutes, for 5 attempts over about two and a half hours. Answer quickly and do slow work in the background.

Deliveries are at least once, so the same event can arrive twice. x-ottoport-delivery stays the same across automatic retries of one delivery; key idempotency on the job id in data.id. The job's webhook field in GET /v1/videos/generations/:id shows every attempt and your endpoint's response.

Redeliver

Sends a finished job's webhook again right away and resets its attempt count, so this also works after all 5 attempts have failed. Redelivery gets a new x-ottoport-delivery id. You can do the same from the Webhooks page in the dashboard, which lists every delivery by workspace.

curl -X POST https://ottoport.ai/api/v1/videos/generations/$JOB_ID/webhook \
  -H "Authorization: Bearer $OTTOPORT_API_KEY"

Generated files are temporary: their URLs stop working at expires_at, a few days after they are made. A collection keeps them for good. Collections live inside the project of the API key that creates them, so each project — and each team — has its own. Saved files stay until you delete them.

Collections unlock once the account has topped up $10 in total (refunds count against it). Before that, every collection route that would store something answers 403 collections_locked with how much is left to go; listing and deleting always work. Saved files count toward the account's storage allowance, which grows with what it has paid in: 5 GB from $10, 50 GB from $100, 200 GB from $500 and 1 TB from $2,000. Past it, saving answers 413 storage_quota_exceeded, naming the next tier. GET /v1/collections reports the tier, usage and the next tier up.

Save while you generate

Add collection to any image, video, speech or music request. Each output then carries an asset_id and an asset_url that does not expire, alongside the usual temporary url. A locked account or an unknown collection is refused before anything is generated or charged. If one file cannot be saved, the generation still succeeds and that output carries asset_error instead; save it from its url while it lasts.

curl https://ottoport.ai/api/v1/images/generations \
  -H "Authorization: Bearer $OTTOPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "spring campaign hero, pastel, studio light",
    "collection": { "external_id": "campaign-spring", "name": "Spring campaign", "create": true }
  }'

# Each output carries the kept copy:
# "data": [{
#   "url": "https://cdn.ottoport.ai/images/…",          ← expires at expires_at
#   "expires_at": "2026-10-15T09:12:00.000Z",
#   "asset_id": "5b1c…",
#   "asset_url": "https://cdn.ottoport.ai/assets/…"     ← kept until deleted
# }]

Endpoints

# 1. Ask where to put the file
curl https://ottoport.ai/api/v1/uploads -H "Authorization: Bearer $OTTOPORT_API_KEY" \
  -H "Content-Type: application/json" -d '{ "content_type": "image/png", "size": 482113 }'
# → { "upload_url": "https://…", "url": "https://cdn.ottoport.ai/uploads/….png", "headers": { "content-type": "image/png" } }

# 2. PUT the bytes there
curl -X PUT "$UPLOAD_URL" -H "content-type: image/png" --data-binary @face.png

# 3. Keep it (optional — "url" already works as a model input for a day)
curl https://ottoport.ai/api/v1/assets -H "Authorization: Bearer $OTTOPORT_API_KEY" \
  -H "Content-Type: application/json" -d '{ "url": "https://cdn.ottoport.ai/uploads/….png", "collection": "<collection id>" }'

The same collections are in the dashboard under Collections, and in the MCP server as ottoport_list_collections, ottoport_create_collection, ottoport_list_assets, ottoport_save_asset, ottoport_upload_file and ottoport_delete_asset, plus a collection argument on every generate tool.

Returns the catalog in OpenAI list format, enriched with modality, provider, and pricing. Filter by modality with the modality query parameter.

curl "https://ottoport.ai/api/v1/models?modality=video" \
  -H "Authorization: Bearer $OTTOPORT_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "kling-3.0",
      "object": "model",
      "owned_by": "kuaishou",
      "modality": "video",
      "display_name": "Kling 3.0",
      "description": "...",
      "pricing": { "perSecond": 0.084 }
    }
  ]
}

Every model available today, straight from the gateway registry. Chat is priced per 1M tokens (input / output); image per image; video per second.

Errors use standard HTTP status codes and an OpenAI-style error object with a stable code. The type mirrors code for SDK compatibility.

{
  "error": {
    "message": "`model` and `messages` are required",
    "type": "invalid_request",
    "code": "invalid_request"
  }
}

Limits scale with your spend tier. When you exceed them the gateway returns 429 rate_limited — back off with exponential retry and honor any Retry-After header. Need higher throughput or dedicated capacity? Talk to us.

The gateway is the product; every other surface is a thin client over it. Use the one that fits your workflow — they all share the same model ids and one key.