Making Requests

This page covers the conventions shared by every SDKMAX endpoint: base URL, auth, request/response shape, streaming, rate limits, and retries.

Base URL

https://api.sdkmax.com/v1

All OpenAI-compatible endpoints live under /v1, e.g. /v1/chat/completions, /v1/embeddings, /v1/images/generations.

Authentication

Authorization: Bearer sk-your-key

A missing header, or a key that's disabled/expired/out of quota, returns 401 or 403 — see Error Codes.

Request format

• Content-Type: application/json (file-upload endpoints like image edits or audio transcription use multipart/form-data instead).
• Body fields match the OpenAI docs: model, messages, temperature, max_tokens, stream, etc.

curl https://api.sdkmax.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}],
    "temperature": 0.7
  }'

Response format

Successful responses match OpenAI's JSON shape, e.g. chat/completions:

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hi! How can I help?" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 }
}

Errors are always shaped as:

{
  "error": {
    "message": "Human-readable message, usually includes a request ID",
    "type": "new_api_error",
    "code": "invalid_request"
  }
}

Streaming (SSE)

Set stream: true for Server-Sent Events, protocol-identical to OpenAI:

{ "model": "gpt-4o", "messages": [...], "stream": true }

Read data: -prefixed JSON lines until data: [DONE]. Official OpenAI SDKs handle this exactly the way they would against OpenAI directly.

Rate limits and quota

• Each API key can have a quota cap set at creation; exhausting it returns 429 (or 403, depending on how the limit is configured).
• The platform may also enforce request rate limits per key/account; bursting too many requests returns 429 as well.
• Clients should implement exponential backoff on 429/5xx (e.g. 1s, then doubling, with a max retry count).

Model availability

GET /v1/models returns the models currently available on the gateway (kept in sync with upstream channels automatically):

curl https://api.sdkmax.com/v1/models \
  -H "Authorization: Bearer sk-your-key"

Idempotency and retries

• Timeouts / 5xx: safe to retry (for idempotent GETs, or requests that didn't produce a side effect).
• 4xx errors (400/401/404): fix the request first — retrying won't help.
• Long-running jobs (image/video generation): these return a task ID that you poll separately — see Images API and Video API.

Next steps

• Compatibility scope: OpenAI-Compatible API
• Use an SDK directly: Python · Node.js · Java · Go