Getting started

A call to the JSON API is one HTTPS POST of a JSON body to https://api.voplica.com. This page takes you from a new account to your first two calls: one that needs no key, and one made with your key.

Native gRPC

The native gRPC endpoint opens soon. Today the JSON API is served, and the client libraries for TypeScript, Java, Python and Go give you type-safe requests and responses for it: they write a typed request as the JSON the API takes, and read its JSON answer back into a typed response.

What you need

• An account. Sign in at voplica.com with Google or Apple. You must be at least 18 years old to use Voplica.
• Credits, for the calls that cost something. API usage is paid with Anytime and Earned credits only — free credits and plan credits can’t be used for the API. A credit pack from the pricing page adds Anytime credits. Billing and limits explains what a call costs.
• An API key, created below.

Create an API key

1. In the studio, open Profile → API keys, at voplica.com/profile/api-keys.

2. Give the key a name, for example the name of your app, and choose when it expires. In 90 days is preselected; you can also choose 30 or 365 days, or Never.

3. Choose Create key, then Copy key. The key starts with pat_, and the studio shows it only this once.

4. Keep the key on your server, for example in an environment variable:

   export VOPLICA_API_KEY=pat_your_api_key

Keep your key secret

A key acts as you and spends your credits. Use it only on your own server: never put it in a web page, in an app that other people install, or in a public repository. If a key leaks, revoke it on the API keys page.

Make a call without a key

Some methods answer without a key. This one returns the model variant Voplica recommends as a starting point:

curl

curl -X POST https://api.voplica.com/voplica.api.ai.model.ModelVariantService/GetRecommendedBaseModelVariant \
  -H 'Content-Type: application/json' \
  -d '{}'

TypeScript

You need Node 22.18 or later, which runs TypeScript files directly. Install the client, Connect and its Node transport from npmjs.com, with no .npmrc and no token (Clients also shows how to install from GitHub Packages):

npm install @voplica/connect @connectrpc/connect @connectrpc/connect-node

Save this as anonymous.ts in a project whose package.json has "type": "module", then run node anonymous.ts:

anonymous.ts

import { createClient } from "@connectrpc/connect";
import { createConnectTransport } from "@connectrpc/connect-node";
import { ModelVariantService } from "@voplica/connect";

const transport = createConnectTransport({
  baseUrl: "https://api.voplica.com",
  httpVersion: "1.1",
  useBinaryFormat: false, // send and receive JSON
});

const modelVariants = createClient(ModelVariantService, transport);
const { modelVariant } = await modelVariants.getRecommendedBaseModelVariant({});
console.log(modelVariant?.variantId, modelVariant?.variantName);

The path is the method’s full name, /<package>.<Service>/<Method>. The body {} is a request with every field left unset. The answer is the response message as JSON, shortened here:

{
  "modelVariant": {
    "variantId": "…",
    "variantName": "…",
    "modelFamily": "…",
    "status": "PUBLISHED",
    "visibility": "PUBLIC"
  }
}

Make a call with your key

This one returns your credit balance. The key goes in the Authorization header:

curl

curl -X POST https://api.voplica.com/voplica.api.payment.PaymentService/GetBillingInfo \
  -H "Authorization: Bearer $VOPLICA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

TypeScript

An interceptor adds the key to every call. Save this as balance.ts and run node balance.ts in the shell where you set VOPLICA_API_KEY:

balance.ts

import { createClient, type Interceptor } from "@connectrpc/connect";
import { createConnectTransport } from "@connectrpc/connect-node";
import { PaymentService } from "@voplica/connect";

// The key comes from the environment, never from your code.
const apiKey = process.env.VOPLICA_API_KEY;
if (!apiKey) {
  console.error("Set VOPLICA_API_KEY to your API key first.");
  process.exit(1);
}

const withApiKey: Interceptor = (next) => (request) => {
  request.header.set("Authorization", `Bearer ${apiKey}`);
  return next(request);
};

const transport = createConnectTransport({
  baseUrl: "https://api.voplica.com",
  httpVersion: "1.1",
  useBinaryFormat: false,
  interceptors: [withApiKey],
});

const payments = createClient(PaymentService, transport);
const { billingInfo } = await payments.getBillingInfo({});
console.log(billingInfo?.permanentCreditsMilli, billingInfo?.earnedCreditsMilli);

The answer, shortened:

{
  "billingInfo": {
    "accountId": "…",
    "permanentCreditsMilli": "2500000",
    "earnedCreditsMilli": "0"
  }
}

permanentCreditsMilli is your Anytime credits and earnedCreditsMilli your Earned credits, both in thousandths of a credit. 64-bit numbers like these come back as JSON strings; the TypeScript client gives them as bigint values.

Where next

AuthenticationHow keys work, and what a key can and cannot do.

The JSON APIThe protocol, the JSON mapping, the errors and the limits.

API referenceEvery method, with its request and its response.

ClientsType-safe requests and responses in TypeScript, Java, Python and Go.

Generating images and videosRun a workflow, follow it and fetch what it made.