Sunra API: A Practical Guide to Unified Multimodal AI Inference

The Sunra API is a developer platform for calling multimodal AI models and large language models through production-oriented APIs, SDKs, and a queue system. Its core value is not that every model has the same capability. It is that an application can discover models, authenticate with one account key, submit jobs, track long-running work, and choose an API format that fits its stack.

That distinction matters. A unified API can reduce integration work, but it does not erase model-specific schemas, output limits, latency, safety behavior, licensing, or pricing rules. The sensible way to evaluate Sunra is as an inference platform: inspect the exact endpoint you need, pin the model and parameters, measure the complete workflow, and keep a fallback plan.

This guide explains what the Sunra API is, how it is structured, how to make a first request, how to handle authentication and asynchronous jobs, how pricing is calculated, and what to test before putting it behind a customer-facing feature. It covers the developer platform at platform.sunra.ai and docs.sunra.ai, not the separate Sunra creative workspace at sunra.ai.

Research reviewed October 29, 2026. API behavior and examples in this article are based on Sunra's public documentation; prices, model availability, and terms can change. The illustrations are conceptual editorial diagrams, not diagrams of Sunra's internal infrastructure.

Table of contents

• Sunra API at a glance
• What the platform actually unifies
• The two API families and authentication
• First multimodal request
• Queues, status, and webhooks
• LLM-compatible endpoints
• Pricing and cost estimation
• Security and production architecture
• SDKs, files, and model schemas
• How to evaluate Sunra in practice
• Common questions
• Sources and verification notes

Sunra API at a glance

Question	Evidence-led answer
What is Sunra?	An all-in-one model platform offering multimodal inference and LLM APIs.
What can it generate or process?	Depending on the selected model and endpoint: images, video, speech, text, embeddings, and other model-specific outputs.
What is the main multimodal base URL?	https://api.sunra.ai for prediction and queue APIs.
What is the LLM base URL?	https://api-llm.sunra.ai for OpenAI-compatible and Anthropic-compatible endpoints.
How is authentication handled?	One Sunra API key works for both API families, but the raw HTTP authorization schemes differ.
Does every endpoint respond immediately?	No. Longer multimodal jobs use a queue with request status and result endpoints.
Are all requests priced the same way?	No. Sunra documents both pre-defined prices and post-calculated usage settlement.
Is it a drop-in replacement for every provider?	No. Compatibility exists at particular API formats; model schemas and capabilities still require review.

Sunra's documentation describes the service as a unified access layer for both diffusion/media models and LLMs. The same documentation also separates those product surfaces: multimodal predictions use api.sunra.ai, while LLM requests use api-llm.sunra.ai. The split is useful because it makes the request contract explicit instead of pretending that image generation and chat completion are one protocol.

What the platform actually unifies

The word unified can mean several different things in AI infrastructure. In Sunra's case, it primarily means a common account, catalog, authentication model, client-library experience, and queue pattern around a broad set of model endpoints. It does not mean a prompt written for one model can be sent unchanged to every other model.

An image endpoint may need a prompt, dimensions, an output format, or reference images. A video endpoint may add duration, resolution, and reference material. A language endpoint expects messages or input items and may support tools, structured outputs, or streaming. A speech endpoint has its own audio formats and limits. The endpoint's model schema remains the source of truth.

This architecture is valuable when an application needs to compare models or add a new modality without creating an entirely separate billing and job-tracking integration for each provider. It is less valuable if a product uses one narrow model and already has a mature direct integration. In that case, the extra platform layer should earn its place through catalog breadth, operational simplicity, routing, or support.

The first engineering decision is therefore not “How do I call Sunra?” It is “Which model endpoint, input schema, output contract, and failure mode does my feature need?” Treat the model ID and endpoint path as part of the feature configuration, not as incidental strings buried in application code.

The two API families and authentication

Sunra's authentication documentation specifies one API key for both product APIs, with different raw HTTP schemes:

• Multimodal prediction and queue requests use Authorization: Key $SUNRA_KEY against api.sunra.ai.
• LLM completion requests use Authorization: Bearer $SUNRA_KEY against api-llm.sunra.ai.

The difference is easy to miss when an application starts with an SDK and later adds a direct HTTP call. A valid key with the wrong scheme can look like an account or permission problem. Keep the base URL, auth scheme, and endpoint family together in a typed configuration object.

The official recommendation is to store the key in an environment variable such as SUNRA_KEY. A key grants access to the account balance, so it should be handled like a password. Never put it in browser JavaScript, a mobile application bundle, a public repository, or a URL query string. If a browser needs to start a generation, send an authenticated request to your own server and let that server call Sunra.

One minimal multimodal request with curl looks like this:

curl -X POST \
  https://api.sunra.ai/v1/queue/black-forest-labs/flux-kontext-pro/text-to-image \
  -H "Authorization: Key $SUNRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A technical notebook showing a small robot sorting colored cables",
    "width": 1024,
    "height": 768,
    "output_format": "jpeg"
  }'

The example illustrates the request shape, not a recommendation for that model or a guarantee that the same parameters are accepted by every endpoint. Before sending production traffic, inspect the endpoint schema and current model catalog.

First multimodal request

The JavaScript/TypeScript client is designed to make an endpoint call concise. Sunra's quickstart shows installation with npm install @sunra/client, the SUNRA_KEY environment variable, and a sunra.subscribe() call that waits for the result:

import { sunra } from "@sunra/client";

const result = await sunra.subscribe(
  "black-forest-labs/flux-kontext-pro/text-to-image",
  {
    input: {
      prompt: "A rabbit wearing glasses reading under a mushroom, watercolor style",
      width: 1024,
      height: 768,
      output_format: "jpeg",
    },
  },
);

console.log(result.data);

The important behavior is that subscribe() is a convenience over a queued request. For a command-line experiment, waiting is convenient. For a web product, a durable job record is usually better: create a local job, submit to Sunra, store the request ID, update status asynchronously, and show the user a recoverable state if the browser closes.

A robust first integration also records the model identifier, endpoint, request parameters, provider or routing choice if applicable, request ID, timestamps, and the final output reference. Do not store the API key in that record. If prompts may contain personal or confidential data, define retention and access rules before logging them.

Queues, status, and webhooks

Long-running AI jobs create a different product problem from ordinary HTTP. A request may wait for capacity, run for several seconds or minutes, fail upstream, or complete after the user has navigated away. Sunra's queue API returns a request_id plus URLs for status, result, and cancellation.

The documented lifecycle includes IN_QUEUE, IN_PROGRESS, and COMPLETED; a completed response includes a success flag and an error object when the prediction failed. The streaming status endpoint sends server-sent events until a terminal state. A webhook can notify your server when a queued request reaches a terminal state, which removes the need to keep a worker polling every request.

Treat the queue as an external state machine. Your webhook handler should be idempotent: the same callback must not grant a user two outputs, charge your internal ledger twice, or advance a job incorrectly. Verify that the callback belongs to the request and model you created, validate its payload, and make the state transition conditional on the current local state.

For polling, use bounded backoff and a server-side timeout. For streaming, close the connection when the documented terminal event arrives. For webhooks, return a fast success response after durable validation and move heavier processing to your own queue. These patterns protect both your server and the user experience when upstream load changes.

LLM-compatible endpoints

Sunra documents four LLM API formats under https://api-llm.sunra.ai:

1. Chat Completions at /v1/chat/completions, using the OpenAI Chat Completions format.
2. Anthropic Messages at /v1/messages, using Anthropic's message format and features such as extended thinking and tool use where supported.
3. Responses at /v1/responses, using the OpenAI Responses format for flexible input items and features such as tools and structured output where supported.
4. Embeddings at /v1/embeddings, using the OpenAI embeddings format for vectors used in search, clustering, classification, and retrieval-augmented generation.

All four use Bearer authentication. The compatible format can reduce migration work for a client already built around the OpenAI or Anthropic SDK, but compatibility is not proof of identical behavior. Check model IDs, streaming semantics, tool support, context and output limits, structured-output guarantees, and provider routing before treating a migrated request as equivalent.

A simple OpenAI-compatible request is conceptually:

curl -X POST https://api-llm.sunra.ai/v1/chat/completions \
  -H "Authorization: Bearer $SUNRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "Summarize this incident in three bullets."}
    ]
  }'

For long generations, the documentation recommends streaming because a non-streaming response that takes too long can be terminated at the edge. That is an operational constraint, not merely a user-interface preference. Your client should handle partial output, disconnects, retries, and the difference between a completed response and a cancelled stream.

Pricing and cost estimation

Sunra's pricing documentation makes an important distinction between pre-defined and post-calculated billing.

For a pre-defined endpoint, the platform can determine the charge from request parameters before the job runs. This makes a quote predictable when the model's resolution, duration, number of images, or other options are known. For a post-calculated endpoint, Sunra may reserve an upper-bound amount at submission and settle the final amount from actual usage after completion, releasing the difference.

Do not estimate a video job with an image price, or assume that the visible model name is enough to calculate a charge. Duration, resolution, reference materials, output size, and token usage can all matter. Video may be billed per output second; reference-to-video may add charges for reference material; some image endpoints count reference images or prompt tokens.

Sunra documents programmatic pricing endpoints:

• GET /v1/models lists model IDs and does not require an API key.
• GET /v1/pricing lists price cards, including human-readable display and tooltip fields, and uses API-key authentication.
• GET /v1/pricing/model/{model_id}/endpoint/{endpoint} returns machine-readable rules for a specific model endpoint.

The pricing list is paginated. In an application that needs a preflight estimate, resolve the model ID, fetch the endpoint rule, evaluate the request parameters according to the documented order, and show the user the assumptions. Cache catalog data carefully and include a refreshed-at timestamp, because pricing and model availability are mutable.

The business metric to watch is not only cost per request. Measure cost per accepted result. If an image is generated three times before a reviewer accepts one, the accepted result includes the failed or rejected attempts. Add retries, moderation rejects, storage, post-processing, and any human review when calculating unit economics.

Security and production architecture

The smallest safe production shape is:

1. The client sends a validated feature request to your backend.
2. Your backend authenticates the user, enforces quotas and content policy, and selects an allowed model endpoint.
3. Your backend submits to Sunra with the server-held key.
4. Your backend stores the external request ID and a redacted job record.
5. A worker, polling loop, or webhook updates the job and returns a safe result to the client.

The client should not be allowed to choose arbitrary provider endpoints if that choice could bypass your budget, privacy, or content controls. Keep an allow-list of models for each product feature. Validate user-supplied dimensions, duration, reference URLs, file types, and prompt length before submission. Apply per-user and per-IP rate limits where abuse is possible.

For uploaded files, Sunra's JavaScript documentation describes storage upload support and a maximum file size of 100 MB. That is not a complete application policy. Your own service should set a lower limit when practical, validate MIME types and content, scan or quarantine untrusted files, and avoid retaining a private source file longer than needed. A URL accepted by a model is not automatically safe to fetch from every origin.

Log enough to debug without turning logs into a copy of the user's private data. A useful record includes a job ID, model, endpoint, status, timing, response size, error class, and cost metadata. Redact API keys, auth headers, private file URLs, and sensitive prompt content. Make the data retention rule explicit.

SDKs, files, and model schemas

Sunra's public client documentation covers JavaScript/TypeScript, Python, Java, and other integrations, while the official client repository provides examples and a server-proxy package for several common frameworks. SDK ergonomics are helpful, but an application should still understand the HTTP contract beneath them. This makes provider errors, timeouts, and version changes easier to diagnose.

The JavaScript client can upload a File, Blob, or data URI to Sunra storage and then pass the resulting URL to a model endpoint. Automatic upload is convenient for prototypes; for production, decide whether your application should upload directly, issue a short-lived upload permission, or proxy the file through a scanner and policy layer first.

Model schemas are especially important for a multi-model platform. Use the catalog or schema endpoint to discover the input fields, then pin a tested configuration. A model alias may be human-friendly, but reproducibility depends on recording the actual model and endpoint version available to your account at the time of the request.

How to evaluate Sunra in practice

The fairest evaluation is a workflow comparison, not a demo comparison. Start with a small set of representative tasks from your product: easy cases, normal cases, edge cases, and intentionally failing inputs. For each task, define acceptance criteria before running the model.

Measure at least:

• Correctness: Did the output satisfy the task and preserve required constraints?
• Quality: Is the image, video, audio, or text usable without disproportionate editing?
• Latency: How long did the complete workflow take, including queueing, processing, transport, and retries?
• Reliability: What percentage completed successfully, and what failure classes occurred?
• Cost: What did the full attempt cost, including rejected results and retries?
• Operations: Were request IDs, statuses, webhooks, logs, and cancellations easy to manage?
• Security: Were credentials, uploads, prompts, and outputs handled according to your policy?

Run the same task set with a baseline integration when possible. Keep the prompt, input asset, model configuration, timeout, and acceptance check comparable. Record the date, model ID, endpoint, provider, SDK version, and pricing snapshot. A single successful image or answer proves that a path works; it does not establish consistency.

For a user-facing feature, include recovery tests: close the browser while a job is queued, send the same request twice, cancel an in-progress job, deliver a duplicate webhook, exceed a quota, and retry after a transient provider error. The system should fail in a way the user can understand, and it should not double-charge your internal account or create duplicate business records.

If you want to compare model availability or build a gateway-based prototype, start with the 01Router model gateway. Use the 01Router API documentation to confirm the selected integration contract, then check the 01Router pricing page before making a cost promise. These links are product-navigation resources, not evidence that every Sunra model is currently available through 01Router.

Common questions

Is Sunra API the same as the Sunra web app?

No. Sunra presents a creative workspace at sunra.ai and a developer platform at platform.sunra.ai. They may share an account ecosystem, but an API integration should follow the developer documentation, API base URLs, key management, model catalog, and terms that apply to the API.

Does Sunra API provide one endpoint for every model?

No. It provides a unified platform around model-specific endpoints. The model path, input schema, output type, supported features, and limits can differ. Use the endpoint schema and model documentation instead of assuming universal parameters.

Can I expose the Sunra API key in a frontend app?

You should not. The official authentication guidance treats the key as a credential with access to account balance. Keep it on a backend or use a server-side proxy pattern, then give the browser only the narrowly scoped result or job status it needs.

What is the difference between sunra.subscribe() and queue methods?

subscribe() is a convenience that submits a request and waits for the result. Queue methods let an application submit a job, persist its request ID, inspect status, retrieve the result later, or cancel it. The latter is usually more appropriate for a durable web workflow.

Can I use OpenAI's SDK with Sunra LLM endpoints?

The documentation describes OpenAI-compatible Chat Completions, Responses, and Embeddings endpoints. Compatibility reduces client changes, but you still need to verify model IDs, supported parameters, tools, streaming, limits, and error behavior for the chosen model.

How should I calculate Sunra API cost?

Start from the current model and endpoint pricing rule. Include every request parameter that affects billing, then add retries, rejected outputs, post-processing, storage, and review. For post-calculated endpoints, distinguish any reserved upper bound from the final settled charge.

Is Sunra a replacement for direct model-provider APIs?

It can be a useful abstraction when unified access, model choice, queue management, or one operational surface matters. It is not automatically a replacement. Compare support, data handling, latency, pricing, model availability, contractual terms, and failure recovery for your specific workload.

Sources and verification notes

• Sunra documentation: Introduction — platform scope and the July 2026 developer-site move.
• Sunra documentation: Authentication — API keys, base URLs, authorization schemes, and key security.
• Sunra documentation: Multimodal Quickstart — SDK installation and a first endpoint call.
• Sunra documentation: Queue — queue submission, statuses, streaming, cancellation, and webhooks.
• Sunra documentation: LLM Quickstart — Chat Completions, Messages, Responses, and Embeddings formats.
• Sunra documentation: Pricing — pricing API, pre-defined prices, post-calculated settlement, and examples.
• Sunra documentation: JavaScript / TypeScript — SDK, queue helpers, storage uploads, and file-size guidance.
• Sunra AI official client libraries — supported clients and examples.

This article was reviewed on October 29, 2026. The documented API mechanics above are factual summaries of the linked sources. The architecture recommendations, evaluation checklist, and cost-per-accepted-result framing are editorial guidance. Recheck model availability, prices, limits, privacy terms, and supported parameters immediately before implementation.