Partner API

Developer docs for white-label partners that bring their own users: the sign-in hand-off, per-user credits, usage for your monthly invoice, and user management.

The Partner API connects your own product to your Sozee white-label site. It is for companies that already have their own login and users: you sign those users in to Sozee from your server, give them credits, read what they used, and manage their accounts.

View as Markdown · OpenAPI document · Questions: support@sozee.ai

Your users never buy anything from Sozee. You decide how many credits each user has, and Sozee invoices you each month for the credits your users spent.

How it works

Your user clicks. A button such as "Open studio" on your site.
Your server calls. POST /sessions with your id for that user.
You redirect. The browser goes to the launch_url in the answer.
Signed in. The user lands on your Sozee site. No second login, no Sozee password.
Credits and usage. Your server adds credits and reads balances and usage whenever it needs to.

Before you start

Sozee gives you:

Your site address, for example yourbrand.sozee.ai. This is where your users create.
An API key that starts with szp_live_. Sozee creates it for you and shows it once: store it in your secrets manager straight away.

You give Sozee:

Your logo and brand color, for the look of your site.
signInUrl: the page on your site that starts a Sozee session (the route in Sign your users in). Sozee sends signed-out visitors there.
creditsUrl: the page on your site where a user gets more credits. Sozee links to it when a user runs out.

Your API key is a secret. Use it only on your server. Never put a key in a browser, a mobile app, a public repository or a log.

Optional settings

Sozee can switch these on for your site. Both are off unless you ask.

A "Help" link in the studio menu that opens your own help center. Give us the URL.
Sozee's support chat in the studio. The chat window carries Sozee's name.

Quickstart

Replace szp_live_… with your key. First, check it:

curl https://app.sozee.ai/api/partner/v1/me \
  -H "Authorization: Bearer szp_live_…"

Answer

{
  "partner_id": "yourbrand",
  "name": "Your Brand",
  "environment": "live",
  "site_url": "https://yourbrand.sozee.ai"
}

Create a sign-in link for one of your users:

curl -X POST https://app.sozee.ai/api/partner/v1/sessions \
  -H "Authorization: Bearer szp_live_…" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user_8f2c1", "email": "sam@example.com", "name": "Sam Lee"}'

Answer

{
  "launch_url": "https://yourbrand.sozee.ai/launch?code=one-time-code",
  "expires_in": 120,
  "user": {
    "user_id": "user_8f2c1",
    "status": "active",
    "created_at": "2026-11-12T21:31:30.846Z",
    "credits": {
      "balance": 0.0
    }
  }
}

Open the launch_url in a browser within 120 seconds and you are signed in as that user. A new user has 0 credits, so give them some:

curl -X POST https://app.sozee.ai/api/partner/v1/credits \
  -H "Authorization: Bearer szp_live_…" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user_8f2c1", "amount": 50, "reference": "inv_2026_11_0042"}'

Answer

{
  "user_id": "user_8f2c1",
  "balance": 50.0,
  "amount": 50.0,
  "reference": "inv_2026_11_0042",
  "replayed": false
}

Credit amounts come back as JSON numbers with a decimal point, for example 50.0.

Base URL and authentication

What	Value
Base URL	`https://app.sozee.ai/api/partner/v1`
Key prefix	`szp_live_`
Body format	JSON, with `Content-Type: application/json`

Every call except GET /openapi.json needs this header:

Header

Authorization: Bearer szp_live_…

A missing or wrong key is refused with 401 invalid_api_key.

Testing

To try your integration without touching real users, use a made-up user_id such as test_user_1 and delete it when you are done. If you want a separate test site with its own address and key, ask us.

Key rotation

Sozee creates your keys. Two can be live at once, so you can rotate without downtime: ask us for a new key, deploy it, check your calls succeed with it, then ask us to revoke the old one.

Sign your users in

POST /sessions creates a one-time sign-in link for one user.

Body

{"user_id": "user_8f2c1", "email": "sam@example.com", "name": "Sam Lee"}

user_id is required. It is your id for the user, exactly as you store it. It travels in the request body, never in the URL, so it may contain any characters, including /, +, @ and |. It is case-sensitive and never trimmed.
Do not send an email address as user_id unless an email address is your user id: a user who changes their email would become a new user.
name is optional and is shown to the user in the studio's account menu.
email is optional and is kept for your and our reference only. It is never shown to the user, never used to sign in and never emailed by Sozee.

The first call for a new user_id creates the user. There is no import step and no separate create call. The answer carries the user in the same shape as GET /user:

Answer

{
  "launch_url": "https://yourbrand.sozee.ai/launch?code=one-time-code",
  "expires_in": 120,
  "user": {
    "user_id": "user_8f2c1",
    "status": "active",
    "created_at": "2026-11-12T21:31:30.846Z",
    "credits": {
      "balance": 0.0
    }
  }
}

Create the link on click. The link works once and expires 120 seconds after it is created. Create it at the moment the user clicks, on every click, and redirect at once. Never create links ahead of time, store them, email them or put them in a page.

If the user is disabled or deleted, the call answers 409 user_disabled or 409 user_deleted and no link is created. Show your own message in that case.

Example route

This route checks your own login, asks Sozee for a link and redirects. The Node version uses the fetch built into Node 18 and later.

Node (Express)

import express from "express";
import session from "express-session";

const SOZEE_API = process.env.SOZEE_API_BASE; // https://app.sozee.ai/api/partner/v1
const SOZEE_KEY = process.env.SOZEE_API_KEY;  // szp_live_…, server-side only
const UNAVAILABLE = "The studio is not available right now. Try again in a minute.";

const app = express();
app.use(session({ secret: process.env.SESSION_SECRET, resave: false, saveUninitialized: false }));

app.get("/open-sozee", async (req, res) => {
  const user = req.session.user; // set by your own login
  if (!user) return res.redirect("/login?next=/open-sozee");

  try {
    const r = await fetch(`${SOZEE_API}/sessions`, {
      method: "POST",
      headers: { Authorization: `Bearer ${SOZEE_KEY}`, "Content-Type": "application/json" },
      body: JSON.stringify({ user_id: String(user.id), email: user.email, name: user.name }),
      signal: AbortSignal.timeout(10000),
    });
    const body = await r.json();

    if (!r.ok) {
      const code = body.error && body.error.code;
      if (code === "user_disabled" || code === "user_deleted") {
        return res.status(403).send("Your studio access is turned off. Contact support.");
      }
      return res.status(502).send(UNAVAILABLE);
    }

    res.set("Cache-Control", "no-store");
    res.redirect(302, body.launch_url);
  } catch (err) {
    // A timeout, a network error or an answer that is not JSON.
    res.status(502).send(UNAVAILABLE);
  }
});

app.listen(3000);

Python (Flask)

import os
import requests
from flask import Flask, redirect, session, make_response

SOZEE_API = os.environ["SOZEE_API_BASE"]  # https://app.sozee.ai/api/partner/v1
SOZEE_KEY = os.environ["SOZEE_API_KEY"]   # szp_live_…, server-side only
UNAVAILABLE = "The studio is not available right now. Try again in a minute."

app = Flask(__name__)
app.secret_key = os.environ["SESSION_SECRET"]

@app.get("/open-sozee")
def open_sozee():
    user = session.get("user")  # set by your own login
    if not user:
        return redirect("/login?next=/open-sozee")

    try:
        r = requests.post(
            f"{SOZEE_API}/sessions",
            headers={"Authorization": f"Bearer {SOZEE_KEY}"},
            json={"user_id": str(user["id"]), "email": user.get("email"), "name": user.get("name")},
            timeout=10,
        )
        body = r.json()
    except (requests.RequestException, ValueError):
        # A timeout, a network error or an answer that is not JSON.
        return UNAVAILABLE, 502

    if not r.ok:
        code = body.get("error", {}).get("code")
        if code in ("user_disabled", "user_deleted"):
            return "Your studio access is turned off. Contact support.", 403
        return UNAVAILABLE, 502

    resp = make_response(redirect(body["launch_url"], code=302))
    resp.headers["Cache-Control"] = "no-store"
    return resp

What your users see

A first-time user lands on a short character setup. They have 0 credits until you add some, so add credits before or right after their first session.
A link that was already used, or is older than 120 seconds, shows "That link has expired. Go back to Your Brand and open it again." with a link to your signInUrl. There is no automatic redirect.
Users cannot change their email or password inside the studio: their identity is yours. The studio has no sign-up or login form on your site.

Signed-out visitors

Anyone who arrives at your Sozee site signed out, for example from a bookmark, is sent to your signInUrl once. If they come straight back still signed out, they see "Open Your Brand from your Your Brand account." with a link. So signInUrl must either start a session or show your own login: point it at the same /open-sozee route. After signing out, a user sees "You're signed out." with a link back to you.

Note. Opening your Sozee site signs that browser out of any other Sozee account it was signed in to.

Credits

Every user starts with 0 credits. Two calls change a balance, and both create the user if Sozee has never seen them, so you can give credits before the first sign-in:

POST /credits adds credits: user_id, amount and reference. amount is a JSON number above 0, with at most 2 decimals, at most 1,000,000.
POST /credits/set sets the balance to an exact number: user_id, balance and reference. balance is 0 to 1,000,000, with at most 2 decimals. Use it for monthly allowances (set to 300 on the first of the month) and for expiry (set to 0).

Numbers must be JSON numbers: a string such as "50" is refused with 422 validation_error.

curl -X POST https://app.sozee.ai/api/partner/v1/credits/set \
  -H "Authorization: Bearer szp_live_…" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user_8f2c1", "balance": 20, "reference": "allowance_2026_12_user_8f2c1"}'

Answer

{
  "user_id": "user_8f2c1",
  "balance": 20.0,
  "previous_balance": 50.0,
  "reference": "allowance_2026_12_user_8f2c1",
  "replayed": false
}

The balance in a credits answer is the balance right after your change.

The reference makes retries safe

Every credit call needs a reference of 1 to 128 characters. Use your own transaction or invoice id. One reference identifies one credit operation for your whole account, not per user:

Repeating the identical call is always safe. It changes nothing and answers "replayed": true, even if the user was disabled or deleted in between. On a replay, balance is the balance now (absent for a deleted user), and for a set, previous_balance is the value from the first time.
Reusing a reference with a different user, a different amount or balance, or on the other credit call is refused with 409 reference_conflict.
A new reference for a disabled or deleted user is refused with 409 user_disabled or 409 user_deleted.

Retry with the same reference. If a credit call times out, send exactly the same call again. You will never add credits twice.

POST /credits/set answers 409 balance_changed if the user's balance kept changing while Sozee tried to set it, for example while they were generating. Wait a moment and send it again with the same reference.

Reading a balance

curl -G https://app.sozee.ai/api/partner/v1/user \
  -H "Authorization: Bearer szp_live_…" \
  --data-urlencode "user_id=user_8f2c1"

Answer

{
  "user_id": "user_8f2c1",
  "status": "active",
  "created_at": "2026-11-12T21:31:30.846Z",
  "credits": {
    "balance": 20.0
  }
}

A deleted user answers {"user_id": "user_8f2c1", "status": "deleted"}, with no created_at and no credits. A user_id Sozee has never seen answers 404 user_not_found. Send user_id URL-encoded, as curl --data-urlencode does.

When a user runs out

Credits are spent as the user creates. When a user runs out, they see "You're out of credits. Get more from Your Brand." with a "Get credits" button that opens your creditsUrl in a new tab. Their balance refreshes when they come back. Sozee never sells credits or plans to your users and never shows them Sozee prices.

Usage and your invoice

GET /usage reports credits per user for a date range.

from and to are UTC dates (YYYY-MM-DD). from is included, to is not, so a calendar month is from=2026-11-01&to=2026-12-01. A range can be up to 92 days.
user_id is optional and limits the report to one user.

curl -G https://app.sozee.ai/api/partner/v1/usage \
  -H "Authorization: Bearer szp_live_…" \
  -d from=2026-11-01 -d to=2026-12-01

Answer

{
  "from": "2026-11-01",
  "to": "2026-12-01",
  "complete": true,
  "next_cursor": null,
  "users": [
    {
      "user_id": "user_8f2c1",
      "credits_added": 20.0,
      "credits_spent": 3.0,
      "credits_refunded": 1.0,
      "credits_used": 2.0
    }
  ],
  "totals": {
    "credits_added": 20.0,
    "credits_spent": 3.0,
    "credits_refunded": 1.0,
    "credits_used": 2.0
  }
}

Each user has four numbers:

Field	Meaning
`credits_added`	The net of your adds and balance changes in the range. It can be negative, for example when a set lowered the balance.
`credits_spent`	Credits the user spent on generations.
`credits_refunded`	Credits returned to the user for failed or refunded generations. Netted automatically.
`credits_used`	`credits_spent` minus `credits_refunded`. This is the billable number.

How your invoice is worked out. You are invoiced monthly for credits_used across your users at the rate in your agreement. Credits you add but users do not spend are not billed.

When complete is false, the report was too large for one answer. Call again with the same from, to and user_id, plus cursor set to the next_cursor you received, and add the numbers from each page together. next_cursor is null when complete is true.

Manage users

Each of these calls takes {"user_id": "…"} in the body. A user_id Sozee has never seen answers 404 user_not_found.

Call	What it does
`POST /users/disable`	Takes effect at once: their open studio stops working and they are sent to your `signInUrl`. `POST /sessions` then answers 409 `user_disabled`, so show your own message there. Reversible.
`POST /users/enable`	Lets a disabled user back in. Their credits are where they were.
`POST /users/signout`	Ends the user's Sozee sessions, within about a minute. Call it from your own logout. The user can come back through your site at any time.
`POST /users/delete`	Closes the account for good. That `user_id` can never be used again, and `GET /user` shows `"status": "deleted"`. Billing records are kept. Calling it again answers the same.

Disable, enable and sign out on a deleted user answer 409 user_deleted.

curl -X POST https://app.sozee.ai/api/partner/v1/users/disable \
  -H "Authorization: Bearer szp_live_…" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user_8f2c1"}'

Answer

{"user_id": "user_8f2c1", "status": "disabled"}

Deleting is not erasing. Deleting a user closes their account. It does not erase the content they stored. To have a user's stored content erased, for example for a privacy request, email support@sozee.ai with the user_id.

If Sozee could not finish ending a user's sessions, disable answers 503 revocation_incomplete, and if a delete could not finish, 503 dependency_unavailable. In both cases the user is already blocked. Send the same call again until it succeeds.

Errors

Every error has the same shape. Read code, not message: the message is for people and may change.

Error

{"error": {"code": "user_disabled", "message": "This user is disabled. Enable it first."}}

Status	Code	What to do
400	`invalid_request`	The body is not valid JSON. Fix the request.
401	`invalid_api_key`	The API key is missing or not valid. Check the key.
403	`partner_disabled`	Your partner account is turned off. Contact Sozee.
404	`user_not_found`	Sozee has never seen this `user_id`. Check the id, or create the user with a session or credit call.
404	`not_found`	No such endpoint. Check the path.
405	`method_not_allowed`	Wrong HTTP method for this path. Check the reference.
409	`user_disabled`	The user is disabled. Enable them first if that is what you want.
409	`user_deleted`	The user was deleted. The `user_id` cannot be used again.
409	`reference_conflict`	This reference was already used for a different request. Use a new reference.
409	`balance_changed`	The balance kept changing during a set. Send the same call again shortly.
409	`host_not_supported`	Your site is not on a Sozee address. Contact Sozee.
422	`validation_error`	A field is missing or out of range. `fields` names which. Fix the request.
429	`rate_limited`	Too many calls. Wait for the number of seconds in the `Retry-After` header, then retry.
502	`upstream_unavailable`	Sozee could not reach a service it needs. Retry with backoff.
503	`partner_api_disabled`	New sessions and credit changes are paused. Reads and user management still work. Retry later.
503	`dependency_unavailable`	A service Sozee depends on did not answer. Retry with backoff.
503	`revocation_incomplete`	The user is blocked but some sessions were not ended yet. Retry the same call.
503	`usage_unavailable`	Usage reports are not available right now. Retry later.

A validation error adds fields, which maps each field name to a message:

Error

{
  "error": {
    "code": "validation_error",
    "message": "Some fields are not valid.",
    "fields": {
      "amount": "must be greater than 0"
    }
  }
}

Retry rules

429: wait for Retry-After, then retry.
5xx and network errors: retry with backoff, for example after 1, 2, 4 and 8 seconds.
Credit calls are always safe to retry with the same reference.
Never retry any other 4xx unchanged. Fix the request first. The one exception is 409 balance_changed, which you can send again as it is.

Limits

Limit	Value
Session calls	300 a minute per key
Credit calls	600 a minute per key
Usage calls	120 a minute per key
Other calls	Not limited today
`user_id`	1 to 128 characters, no control characters
`reference`	1 to 128 characters
`amount`	Above 0, at most 2 decimals, at most 1,000,000 per call
`balance` (set)	0 to 1,000,000, at most 2 decimals
Usage range	Up to 92 days

Not available yet

Sites on your own domain. Today your site lives on a sozee.ai address.
Webhooks for credits and usage. Read them with the calls on this page.
A call that lists all your users. Keep your own list of the user_id values you send.
An itemized usage feed. GET /usage gives totals per user.
Teams for your users. Each user works on their own.

Go-live checklist

Your key is stored in your secrets manager and used only on your server. It appears in no browser code, app, repository or log.
Your server calls https://app.sozee.ai/api/partner/v1 with your szp_live_ key, and GET /me answers your site address.
Your /open-sozee route checks your own login, calls POST /sessions on every click and redirects with 302 to launch_url.
You sent Sozee your signInUrl (that same route) and your creditsUrl, and told us whether you want the Help link or the support chat.
You send your own stable user id as user_id, never an email address unless that is your id.
New users get credits before or right after their first session.
Every credit call sends a reference taken from your own records, and your code retries timeouts with the same reference.
Your code handles 409 user_disabled and 409 user_deleted with a clear message to the user.
Your logout calls POST /users/signout, and closing an account on your side calls POST /users/disable or POST /users/delete.
Any made-up test users such as test_user_1 are deleted.
You can produce last month's GET /usage report, following next_cursor until complete is true, and it matches what you expect to be invoiced.

Brief for your AI coding agent

Paste this into your AI coding tool. It is complete on its own.

Goal: connect our product to our Sozee white-label site using the Sozee Partner API.
Our users sign in to our product as they do today. From our product they open the
Sozee studio already signed in. We give them credits and read their usage.

API
- Base URL: https://app.sozee.ai/api/partner/v1 (there is one base URL; keys start szp_live_)
- Header on every call: Authorization: Bearer <key>. JSON bodies with Content-Type: application/json.
- Read the key from an environment variable (SOZEE_API_KEY) and the base URL from SOZEE_API_BASE.
- OpenAPI document (no key needed): https://app.sozee.ai/api/partner/v1/openapi.json
- To test, use made-up user ids such as test_user_1 and delete them afterwards.

Calls
- GET /me -> {partner_id, name, environment: "live", site_url}
- POST /sessions {user_id, email?, name?} -> {launch_url, expires_in: 120, user}
  Creates the user on first use. user has the GET /user shape. Redirect the browser to
  launch_url with a 302.
- GET /user?user_id=... -> {user_id, status ("active" or "disabled"), created_at, credits: {balance}}
  A deleted user -> {user_id, status: "deleted"}. Never seen -> 404 user_not_found.
- POST /credits {user_id, amount, reference} -> {user_id, balance, amount, reference, replayed}
  Adds credits. Creates the user if never seen. amount is a JSON number above 0, at most
  2 decimals, at most 1,000,000 (strings such as "50" are refused).
- POST /credits/set {user_id, balance, reference} -> {user_id, balance, previous_balance, reference, replayed}
  Sets the balance: 0 to 1,000,000, at most 2 decimals.
- GET /usage?from=YYYY-MM-DD&to=YYYY-MM-DD[&user_id=...][&cursor=...]
  -> {from, to, complete, next_cursor, users: [{user_id, credits_added, credits_spent,
     credits_refunded, credits_used}], totals: {same four}}
  UTC dates, from included, to excluded, at most 92 days. credits_used is what we are billed for.
  While complete is false, call again with cursor=next_cursor (same from, to, user_id) and add
  the numbers up.
- POST /users/disable {user_id} -> {user_id, status: "disabled"}
- POST /users/enable {user_id} -> {user_id, status: "active"}
- POST /users/signout {user_id} -> {user_id, status}
- POST /users/delete {user_id} -> {user_id, status: "deleted"} (permanent)
- Unknown user_id: GET /user and the four /users calls answer 404 user_not_found.
- Errors: {"error": {"code": "...", "message": "..."}}. Branch on code, never on message.
  422 validation_error adds "fields": {field name: message}.

Rules that are easy to get wrong
1. The API key is a server-side secret. Never send it to a browser or app, never log it.
2. user_id is our own stable id for the user, sent in the JSON body (or the query string on GET),
   never in the URL path. Send it exactly as we store it. Do not use the email address.
3. Create the launch link when the user clicks, on every click, then redirect at once.
   It works once and expires after 120 seconds. Never cache or pre-create it. Send
   Cache-Control: no-store on the redirect.
4. Every credit call sends a reference from our own records (transaction or invoice id).
   One reference is one credit operation for our whole account. Repeating the identical call
   is always safe and answers replayed: true. Reusing a reference with a different user,
   amount, balance or credit call is 409 reference_conflict.
5. Handle 409 user_disabled and 409 user_deleted from /sessions and the credit calls with a
   clear message to the user. A deleted user_id can never be used again.
6. Retries: on 429 wait for the Retry-After header. On 5xx or a network error retry with
   backoff (1, 2, 4, 8 seconds). Never retry another 4xx unchanged, except 409 balance_changed.
7. New users have 0 credits: add credits before or right after their first session.

Build
- A GET route /open-sozee: if the visitor is not signed in to our product, send them to our
  login and back. Otherwise call POST /sessions with their id, email and name and 302 to
  launch_url. This route's full URL is our signInUrl.
- Our logout calls POST /users/signout. Closing an account calls POST /users/delete.
- Wherever we grant credits (purchase, plan renewal, allowance), call POST /credits or
  POST /credits/set with a reference.
- A monthly job that calls GET /usage for last month, follows next_cursor, and stores the totals.

Definition of done
- GET /me answers environment "live" and our site address.
- Clicking our "Open studio" button lands a signed-in user on our Sozee site, and a second
  click creates a new link.
- With a made-up user_id such as test_user_1: a credit call sent twice with the same reference
  changes the balance once and the second answer has replayed: true; after
  POST /users/disable our own message shows instead of the studio; POST /users/delete removes it.
- The key appears in no client bundle, repository file or log line.
- Usage for a date range returns, and pages are followed until complete is true.

Reference

All paths are relative to https://app.sozee.ai/api/partner/v1. The machine-readable description of every call is the OpenAPI document.

`GET /me`

Check your key and see which partner it belongs to.

Answer

Field	Type	Notes
`partner_id`	string	Your partner id.
`name`	string	Your partner name.
`environment`	string	Always `live`.
`site_url`	string	Your Sozee site address.

Errors: 401 invalid_api_key.

`POST /sessions`

Create a one-time sign-in link for a user. Creates the user on first use.

Body

Field	Type	Notes
`user_id`	string	Your id for the user, 1 to 128 characters, used exactly as sent.
`email`	string, optional	Kept for your and our reference. Never shown to the user, used to sign in or emailed.
`name`	string, optional	Shown to the user in the studio's account menu.

Answer

Field	Type	Notes
`launch_url`	string	Redirect the browser here. Works once.
`expires_in`	integer	Seconds the link stays valid: 120.
`user`	object	The user, in the same shape as `GET /user`.

Errors: 409 user_disabled, 409 user_deleted, 409 host_not_supported, 422 validation_error, 429 rate_limited, 503 partner_api_disabled.

`GET /user`

Read a user's status and credit balance.

Query

Field	Type	Notes
`user_id`	query string	Your id for the user, URL-encoded.

Answer

Field	Type	Notes
`user_id`	string	Your id for the user.
`status`	string	`active`, `disabled` or `deleted`.
`created_at`	string	ISO 8601 UTC with milliseconds. Absent for a deleted user.
`credits.balance`	number	The current balance. Absent for a deleted user.

Errors: 404 user_not_found.

`POST /credits`

Add credits to a user. Creates the user if Sozee has never seen them.

Body

Field	Type	Notes
`user_id`	string	Your id for the user, 1 to 128 characters, used exactly as sent.
`amount`	number	Above 0, at most 2 decimals, at most 1,000,000. A string such as "50" is refused.
`reference`	string	Your own id for this credit operation, 1 to 128 characters. Unique across your account.

Answer

Field	Type	Notes
`user_id`	string	Your id for the user.
`balance`	number	The balance right after the change. On a replay, the balance now (absent for a deleted user).
`amount`	number	The amount added.
`reference`	string	Your reference.
`replayed`	boolean	`true` when this reference was already applied and nothing changed.

Errors: 409 user_disabled, 409 user_deleted, 409 reference_conflict, 422 validation_error, 429 rate_limited, 503 partner_api_disabled.

`POST /credits/set`

Set a user's balance to an exact number, for allowances and expiry. Creates the user if Sozee has never seen them.

Body

Field	Type	Notes
`user_id`	string	Your id for the user, 1 to 128 characters, used exactly as sent.
`balance`	number	0 to 1,000,000, at most 2 decimals.
`reference`	string	Your own id for this credit operation, 1 to 128 characters. Unique across your account.

Answer

Field	Type	Notes
`user_id`	string	Your id for the user.
`balance`	number	The balance right after the change. On a replay, the balance now (absent for a deleted user).
`previous_balance`	number	The balance before the change. On a replay, the value from the first time.
`reference`	string	Your reference.
`replayed`	boolean	`true` when this reference was already applied and nothing changed.

Errors: 409 user_disabled, 409 user_deleted, 409 reference_conflict, 409 balance_changed, 422 validation_error, 429 rate_limited, 503 partner_api_disabled.

`GET /usage`

Report credits added, spent, refunded and used per user for a date range.

Query

Field	Type	Notes
`from`	query, YYYY-MM-DD	First UTC day, included.
`to`	query, YYYY-MM-DD	Last UTC day, not included. At most 92 days after `from`.
`user_id`	query, optional	Limit the report to one user.
`cursor`	query, optional	The `next_cursor` from the previous page.

Answer

Field	Type	Notes
`from`	string	As sent.
`to`	string	As sent.
`complete`	boolean	`false` when more pages follow.
`next_cursor`	string or null	Send it as `cursor` to get the next page. `null` when complete.
`users`	array	One entry per user: `user_id`, `credits_added`, `credits_spent`, `credits_refunded`, `credits_used`.
`totals`	object	The same four numbers summed over this page.

Errors: 404 user_not_found, 422 validation_error, 429 rate_limited, 503 usage_unavailable.

`POST /users/disable`

Block a user at once and end their Sozee sessions. Reversible.

Body

Field	Type	Notes
`user_id`	string	Your id for the user, 1 to 128 characters, used exactly as sent.

Answer

Field	Type	Notes
`user_id`	string	Your id for the user.
`status`	string	The user's status after the call.

Errors: 404 user_not_found, 409 user_deleted, 503 revocation_incomplete.

`POST /users/enable`

Let a disabled user back in.

Body

Field	Type	Notes
`user_id`	string	Your id for the user, 1 to 128 characters, used exactly as sent.

Answer

Field	Type	Notes
`user_id`	string	Your id for the user.
`status`	string	The user's status after the call.

Errors: 404 user_not_found, 409 user_deleted.

`POST /users/signout`

End a user's Sozee sessions, within about a minute. Call it from your own logout.

Body

Field	Type	Notes
`user_id`	string	Your id for the user, 1 to 128 characters, used exactly as sent.

Answer

Field	Type	Notes
`user_id`	string	Your id for the user.
`status`	string	The user's status after the call.

Errors: 404 user_not_found, 409 user_deleted.

`POST /users/delete`

Close a user's account for good. The user_id can never be used again. Calling it again answers the same.

Body

Field	Type	Notes
`user_id`	string	Your id for the user, 1 to 128 characters, used exactly as sent.

Answer

Field	Type	Notes
`user_id`	string	Your id for the user.
`status`	string	The user's status after the call.

Errors: 404 user_not_found, 503 dependency_unavailable.

`GET /openapi.json`

The OpenAPI 3 document for these calls. No key needed.

Answer

Field	Type	Notes
(document)	JSON	The machine-readable description of every call.

Questions about your integration

Email support@sozee.ai and include your partner id. To set up a white-label site, start with the white-label page.

Email support · White label

Explore Sozee

AI Photo Generator for Creators — Type a scene and get a full set of photos of your AI Character — the same face every time, up to 4K. Direct the shot instead of running a shoot day.
AI Video and Reel Generator — Turn your images into video, clone a reel from any link, and give your Character a voice. Short-form video without a camera or a crew.
Direct Every AI Photo You Generate — Set the setting, outfit, shot style, expression and objects before you generate — a photoshoot you direct from the keyboard, with no re-prompting.
AI Photo Editor: Inpaint and 4K Upscale — Brush out what's wrong, change an expression, recolor an outfit and upscale to 4K. Every generation opens into a full editor before you post.
Schedule and Track Posts on Five Platforms — Schedule photos, carousels, reels and stories to five platforms from one queue, then track impressions, reach and engagement for every Character.
Your AI Content Copilot — Tell Copilot what you need and it writes the caption, fills the prompt and schedules the post — with you approving every checkpoint along the way.
AI Content Studio for Influencers — Scale your output without scaling your shoot days. Three photos become an endless feed of on-brand content in your likeness, scheduled and posted for you.
AI Content Studio for Micro-Creators — Look like a full production team before you can afford one. Cast your Character once, then ship a daily feed without a daily shoot.
Create an AI Influencer From Zero — Cast a persona from zero — no photos of you needed. Lock their identity, build a roster, and keep them posting around the clock.
AI UGC Campaigns for Brands — Run creator campaigns end to end: brief, materials, posting, analytics and payouts in one place. Coming soon to Sozee for brands.
Brand Portal: Pay Per View Placements — Put your products into creator content and pay per view, with brand safety and approvals built in. Coming soon to Sozee for brands.
White Label AI Content Studio — Run your own branded AI content studio on Sozee's engine — your name, your pricing, your creators, on infrastructure you don't have to build. Now in beta.
Terms of Service — The terms that govern your use of Sozee: accounts, subscriptions, content ownership, acceptable conduct, and cancellation.
Privacy Policy — How Sozee collects, uses and protects your data — including reference photos, voice samples, and the content you generate.
Acceptable Use Policy — What you may and may not create, upload or publish with Sozee, including our consent, likeness and prohibited content rules.
Refund and Cancellation Policy — How Sozee handles refunds, cancellations and billing disputes, what happens to credits you have already used, and what to expect when you cancel.
18 U.S.C. 2257 Compliance — Sozee's 18 U.S.C. 2257 record-keeping compliance statement for content published on the platform, and how to reach our designated custodian of records.
Anti-Trafficking Policy — Sozee's zero-tolerance policy on trafficking and exploitation — how we detect, report and act on violations, and how to raise a concern with our team.
Complaints and Content Removal — How creators, rights holders and the public can report content on Sozee and request removal, including our review process and expected response times.
Sozee guides — step-by-step help for every part of the studio
About Sozee — the company behind the studio
Contact — support and privacy contacts
Resources — guides for working creators
Sozee MCP server and developer docs — connect an AI agent to a Sozee account

Partner API

On this page

How it works

Before you start

Optional settings

Quickstart

Base URL and authentication

Testing

Key rotation

Sign your users in

Example route

What your users see

Signed-out visitors

Credits

The reference makes retries safe

Reading a balance

When a user runs out

Usage and your invoice

Manage users

Errors

Retry rules

Limits

Not available yet

Go-live checklist

Brief for your AI coding agent

Reference

GET /me

POST /sessions

GET /user

POST /credits

POST /credits/set

GET /usage

POST /users/disable

POST /users/enable

POST /users/signout

POST /users/delete

GET /openapi.json

Questions about your integration

`GET /me`

`POST /sessions`

`GET /user`

`POST /credits`

`POST /credits/set`

`GET /usage`

`POST /users/disable`

`POST /users/enable`

`POST /users/signout`

`POST /users/delete`

`GET /openapi.json`