Build on DeepAstra

Introduction

DeepAstra gives you a single, capability-aware surface over many models. Every model advertises what it can actually do — probed and verified by DeepAstra — and one request works across all of them. Because DeepAstra is protocol-compatible, existing OpenAI clients need no rewrite: change the base URL and key, and you're on DeepAstra.

• • Base URL: https://api.deepastra.ai/v1
• • Auth: a bearer dak_live_… API key
• • Endpoints: /chat/completions, /responses, /models, /embeddings

Authentication

Authenticate with a bearer API key: Authorization: Bearer dak_live_…. Keys are scoped to a project and carry your organization's billing.

Keep keys secret. Never ship a key in client-side code or commit it — call DeepAstra from your backend and store the key in an environment variable.

Quickstart

Set the base URL and key, list models to pick one, then call chat/completions:

curl https://api.deepastra.ai/v1/chat/completions \
  -H "Authorization: Bearer $DEEPASTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "messages": [{"role": "user", "content": "Hello, DeepAstra!"}]
  }'

SDKs

Any OpenAI SDK works with DeepAstra today — set the base URL and your DeepAstra key. A native DeepAstra SDK is on the way.

# No SDK needed — DeepAstra is plain HTTP. Any HTTP client works.
# The examples on this page use cURL for the raw requests.

API reference

All endpoints are under https://api.deepastra.ai/v1. * marks required parameters.

A GET /models response — note DeepAstra's verified capabilities and supported_parameters:

curl https://api.deepastra.ai/v1/models -H "Authorization: Bearer $DEEPASTRA_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "<model>",
      "object": "model",
      "owned_by": "deepastra-api",
      "context_length": 1000000,
      "max_output_tokens": 131072,
      "architecture": { "input_modalities": ["text", "image"], "output_modalities": ["text"] },
      "capabilities": ["chat_completions", "streaming", "tools", "structured_output", "reasoning", "responses", "vision"],
      "supported_parameters": ["max_tokens", "temperature", "top_p", "tools", "response_format", "reasoning"]
    }
  ]
}

Model families & capabilities

Every family speaks the same OpenAI-compatible surface and the same unified reasoningcontrol — the only differences are which capabilities light up and which reasoning-effort levels a model accepts. The tables below are DeepAstra's probe-verified capabilities; the live, per-model source of truth is always GET /v1/models (capabilities and supported_parameters).

Streaming

Set stream: true for token-by-token Server-Sent Events (a final chunk carries usage):

curl https://api.deepastra.ai/v1/chat/completions \
  -H "Authorization: Bearer $DEEPASTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "<model>", "messages": [{"role": "user", "content": "Count from 1 to 5."}], "stream": true}'

Reasoning

DeepAstra exposes a unified reasoning control — one shape across models. Pass reasoningto turn thinking on/off or set effort; DeepAstra translates it to each model's native mechanism. In the OpenAI SDKs, pass it via extra_body.

curl https://api.deepastra.ai/v1/chat/completions \
  -H "Authorization: Bearer $DEEPASTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "messages": [{"role": "user", "content": "What is 23 * 47?"}],
    "reasoning": {"enabled": false}
  }'

When reasoning runs, the model's thinking comes back alongside the answer — in message.reasoning_content (and delta.reasoning_content while streaming). Reasoning tokens are billed and reported under usage.completion_tokens_details.reasoning_tokens:

{
  "choices": [{
    "message": {
      "role": "assistant",
      "reasoning_content": "23 * 47 = 23 * 40 + 23 * 7 = 920 + 161 ...",
      "content": "23 * 47 = 1081."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 96,
    "completion_tokens_details": { "reasoning_tokens": 84 }
  }
}

Structured output

Ask for guaranteed JSON with response_format. DeepAstra applies each model's verified settings, so you get valid JSON regardless of the model's reasoning behavior:

curl https://api.deepastra.ai/v1/chat/completions \
  -H "Authorization: Bearer $DEEPASTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "messages": [{"role": "user", "content": "Give a city and its country as JSON."}],
    "response_format": {"type": "json_object"}
  }'

Vision

Send images alongside text using standard OpenAI content parts. Only models whose capabilities include vision on GET /v1/models accept image input — on GLM those are glm-4.6v and the lighter glm-4.6v-flashx / glm-4.6v-flash. Pass a public URL or an inline data: URI, and send multiple images per message if you need:

# Send an image with your prompt. Use a model whose GET /v1/models "capabilities" include "vision".
curl https://api.deepastra.ai/v1/chat/completions \
  -H "Authorization: Bearer $DEEPASTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "messages": [{"role": "user", "content": [
      {"type": "text", "text": "What is in this image?"},
      {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
    ]}]
  }'

Prefer base64 data URLs. A remote image_url is fetched server-side by the model provider, so images on hosts that block non-browser clients (many news sites and CDNs) can fail to load. Inlining the bytes as a data:image/…;base64,… URL is the most reliable path; keeping images to ~1280px also lowers latency and token cost.

Responses API

DeepAstra serves the OpenAI Responses API at POST /responses on models whose capabilities include responses. client.responses.create(...) in the OpenAI SDKs works unchanged, including streaming (typed events like response.output_text.delta) and the native reasoning parameter:

# The OpenAI Responses API, served stateless. Use a model whose capabilities include "responses".
curl https://api.deepastra.ai/v1/responses \
  -H "Authorization: Bearer $DEEPASTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "input": "Write a haiku about the sea.",
    "max_output_tokens": 200
  }'

Served stateless:

• store is always false — DeepAstra never persists responses (forced off and disclosed as store-off in x-deepastra-adapted when your request asked otherwise)
• previous_response_id and conversation are rejected — send the full input each turn
• background, stored prompt templates (prompt), hosted tools (web_search, file_search, …), item_reference items, and file_id references (in input content or a tool call's output) are rejected — only function tools and inline content
• prompt_cache_key, safety_identifier, and user are dropped (disclosed via x-deepastra-adapted) — they address a shared provider account and aren't brokered per tenant

Rejected parameters return 400 unsupported_parameter naming the parameter.

Request adaptations

So a single request works across every model, the DeepAstra gateway normalizes it for the target model on your behalf — and tells you what it did in the x-deepastra-adapted response header. You always send standard OpenAI; DeepAstra handles the per-model differences:

• system-mergedMultiple system messages are merged into one leading message.
• reasoning-offYour reasoningcontrol is translated to the model's native mechanism.
• structured-thinking-offA response_formatrequest gets the model's verified settings for reliable JSON.
• tool-choice-thinking-offA forced tool_choice ("required"or a named function) gets the model's verified settings so the tool call is honored.

Rate limits

Every API key carries per-minute request (RPM) and token (TPM) limits plus a daily request cap (RPD). Your organization starts on the default tier and limits grow with your usage; a subscription package raises them further, and an org owner or admin can pin an individual key tighter from the console (never looser — key pins are a safety cap, not an upgrade path). Your current limits, remaining allowance, and reset time are on every response in the x-ratelimit-* headers below.

Exceeding a limit returns 429 rate_limit_exceeded with a retry-after header — wait that many seconds and retry (the OpenAI SDKs do this automatically). Sustained 429s mean you need a higher tier or package, not tighter retry loops.

Cached input is cheaper. When a model reports cache-read input tokens (prompt_tokens_details.cached_tokens in the usage block), those tokens are billed at the model's discounted cached-input rate instead of the full input rate — shown as cached_input_per_1m on the models catalog. Repeated context (agent loops, long conversations) costs you less automatically; no code changes needed.

Response headers

Errors

Errors use the OpenAI envelope with a machine-readable code:

{
  "error": {
    "message": "the model does not exist or is not available",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}