AI API quickstart: from API key to first request

Learn the four moving parts

A base URL identifies the API service, an API key authenticates access, a model ID selects a capability, and an endpoint selects a protocol. They must match. Changing a model name alone does not make OpenAI, Anthropic, and Gemini bodies interchangeable, and a consumer chat subscription normally is not an API credential.

Step 1: prepare three variables

Create an API key for this site, copy an exact model ID that supports your endpoint from the model marketplace, and confirm that your balance or quota is usable. Keep keys in server-side environment variables or a secret manager, never in browser code, mobile bundles, Git, screenshots, or ordinary logs.

The examples use this site's recommended Authorization: Bearer. For native-SDK compatibility, this site's /v1/messages also accepts the site key in x-api-key, and Gemini /v1beta/models/... routes accept x-goog-api-key. Direct Anthropic calls additionally require anthropic-version, while direct Google calls use x-goog-api-key. Always use a key created by this site when calling the gateway; do not mix in a provider key.

Copyexport BASE_URL="https://your-service.example"
export API_KEY="your-site-api-key"
export MODEL_NAME="exact-model-id-from-the-marketplace"

In this guide BASE_URL does not end in /v1. Do not create /v1/v1 when an SDK configuration already includes the version segment.

Step 2: send the smallest request

Use curl first because it removes SDK-version, proxy, and automatic-retry variables. This Chat Completions request contains one user message:

Copycurl "$BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$MODEL_NAME\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply only: connected\"}]}"

HTTP 200 plus model text means the host, key, model, and basic protocol work together. Add images, tools, long context, and optional parameters one capability at a time.

Step 3: read a successful response

Chat Completions normally places text in choices[0].message.content, exposes a stop condition in finish_reason, and reports input and output in usage. A length stop can indicate truncation. Empty text may instead accompany a tool call, refusal, safety block, or protocol-specific content item.

Copy{
  "choices": [
    {
      "message": {"role": "assistant", "content": "connected"},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 12, "completion_tokens": 3, "total_tokens": 15}
}

The numbers are illustrative. Preserve the HTTP status, request ID, returned model, stop reason, usage, and latency instead of keeping only visible text.

Step 4: select the right protocol

• For broad SDK compatibility and a messages shape, read the OpenAI-compatible guide.
• For Claude-native content blocks and tools, read the Anthropic Messages guide.
• For this site's implemented Gemini GenerateContent multimodal parts, read the Gemini API guide.

OpenAI introduces Responses API first for new projects. Google now recommends Interactions API, while this gateway's published Gemini-native routes are definitively generateContent and streamGenerateContent, not /v1beta/interactions. A provider's preferred API and a gateway's compatibility surface are separate facts; contract-test every migration.

Migrating from another OpenAI-compatible service

Keep /v1/chat/completions, messages, and a minimal body unchanged at first; replace only the SDK base_url, this site's API key, and the exact marketplace model ID. Do not append /v1 again when the configured base_url already contains it. After the minimal text request works, regression-test streaming events, tool calls, image input, structured output, stop reasons, and usage one at a time. This site does not reproduce every vendor extension, and changing only the model name does not migrate a request to Responses, Anthropic, or Gemini-native semantics.

Step 5: troubleshoot by status

400 normally points to JSON, fields, or context; 401 to the key; 403 to permission; 404 to the base URL, path, or model; 413 to request size; and 429 to temporary limits or account quota. Read the error body before classifying a 5xx: overload can be transient, but an oversized Gemini GenerateContent input or context can also surface as 500 or 504. Preserve redacted error type, message, and request IDs, then use the troubleshooting guide.

Retry only transient 429, network failures, and selected 5xx responses. Honor Retry-After when present, otherwise use exponential backoff with jitter and cap both attempts and elapsed time. Repeating 400, 401, 403, or billing failures only adds load.

Step 6: control cost and key exposure

Bound concurrency, per-minute requests, daily usage, and output for every end user. Start with short inputs and an economical model. Do not log unbounded requests or responses, especially Base64 media, files, personal data, or tool results. Revoke and rotate an exposed key immediately.

Production checklist

• Pin the tested model ID, endpoint, and required fields, and keep regression requests.
• Set connection, first-byte, and total timeouts; parse streaming as complete SSE events.
• Bound retries and make non-idempotent work idempotent or deduplicated.
• Record request ID, status, stop reason, usage, and latency with secret and personal-data redaction.
• Configure per-user spend controls, alerts, a fallback model, and a deprecation review routine.