XVAPI logoXVAPI
HomeConsoleModelsAPI DocsAboutBlog
中文English繁體中文한국어日本語Tiếng ViệtРусский
Sign in
Start Building
API DOCS

Developer Documentation

Everything here is written for XVAPI integrations. Keep the public contract simple: one stable API domain, stable public model aliases, and wallet-based settlement.

Integration Summary

Base URL
https://api.xvapi.com/v1
Alias
Stable public names
Support
ops@xvapi.com
Last updated
2026-09-12
Version
v2026.09.12

Documentation changelog

v2026.09.12·2026-09-12

Public documentation audit

  • Reviewed public endpoints, field-level contracts, and response examples against the current API surface.
  • Clarified image options, multipart upload limits, and retry behavior for application developers.

Docs Overview

API reference, integration guidance, and error recovery

Build against the public `/v1` contract: authenticate safely, discover available models, send valid requests, process responses, and recover from documented failures.

Reading Paths

Quick start
For authentication, base URL, and a first successful request.
Troubleshooting
For status codes, rate limits, access, and retry decisions.
Image API
For generation, edits, parameters, and result handling.

Start Here

Start from the capability you need to integrate

I want to make a first API call

Start with the Base URL, Bearer authentication, and a small documented request.

Read quickstart↗

I need to diagnose a failed request

Use status codes and retry guidance to determine whether to correct, wait, or contact support.

Open troubleshooting↗

I need image generation or editing

Choose the generation or edit endpoint, validate parameters, and handle `data` results safely.

Read Image API↗
Overview

What your customers integrate with

Your public API should look simple from the outside: one auth model, one customer wallet system, and stable public model aliases.

Stable public domain

Keep a stable public contract so every client integration can stay predictable.

One auth standard

Use one API key format for every documented endpoint.

Wallet settlement + tracing

Every request should be traceable through logs and wallet settlement events.

Quickstart

Get to the first successful call in minutes

The public integration path should be short: create an account, top up balance, issue a key, pick a model name, and call one endpoint.

  1. 1Create an account and top up wallet balance.
  2. 2Issue a customer-facing API key from your platform.
  3. 3Choose a stable public model name from your model list.
  4. 4Call the target endpoint and verify the first successful response.
First successful request
BASE_URL="https://api.xvapi.com/v1"
AUTH_HEADER="Authorization: Bearer YOUR_XVAPI_API_KEY"

curl $BASE_URL/chat/completions \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [
      { "role": "system", "content": "You are a concise assistant." },
      { "role": "user", "content": "Say hello." }
    ],
    "temperature": 0.7
  }'
SDK Examples

Use official SDKs with the XVAPI base URL

Most clients can keep their SDK usage pattern and only switch the API key. Start from the Responses API unless you need classic chat-completions compatibility.

JavaScript / TypeScript
import OpenAI from "openai";

const BASE_URL = "https://api.xvapi.com/v1";

const client = new OpenAI({
  apiKey: "YOUR_XVAPI_API_KEY",
  baseURL: BASE_URL,
});

const response = await client.responses.create({
  model: "gpt-4.1-mini",
  input: "Write a short launch checklist."
});

console.log(response.output_text);
Python
from openai import OpenAI

BASE_URL = "https://api.xvapi.com/v1"

client = OpenAI(
    api_key="YOUR_XVAPI_API_KEY",
    base_url=BASE_URL,
)

response = client.responses.create(
    model="gpt-4.1-mini",
    input="Write a short launch checklist."
)

print(response.output_text)
Image API

Send your first image generation request

Start with `/v1/models`, select an image-capable public alias, then send one small request to `/v1/images/generations` and inspect the returned data item.

When you need this

  • You need a first successful image request before adding advanced options.
  • You need to confirm that the current API key can list an image-capable model.
  • You want to distinguish generation requests from reference-image edits.

Before you start

Store an XVAPI API key in your server-side environment, not in browser code.
Call `/v1/models` with that key before hard-coding a model name.
Use one image and documented options for the first request.

1. Discover an image model

Call `/v1/models` and select an alias whose metadata declares image-generation capabilities.

2. Send one small request

POST to `/v1/images/generations` with model, prompt, and one supported size or quality option.

3. Inspect the response

Read the first item in data and handle the URL or base64 payload returned for that model.

4. Add options gradually

Only after the baseline succeeds should you add n, quality, size, or reference-image editing.

Most common mistakes

The model list appears, so the request must work

Not necessarily. Listing a model and successfully calling that model are two different checks. A model can remain visible while its current service configuration is unavailable.

Putting an API key in browser code

Do not expose API keys in browser code or public repositories. Keep keys in your application's server-side environment.

Start with multi-image generation

That makes debugging harder. First verify one-image generation. Only after that should you try multi-image or reference-image flows.

What to do next

If verification succeeds but generation still fails, continue with the troubleshooting article about timeouts and model availability.
If you plan to use reference images, move on to the guide about the edits workflow rather than repeating plain generation.
If you are unsure which image model to keep public, review the model guide before exposing more aliases.
Review quickstartReview API Key RulesView Models
Image Edits API

Edit an image with a reference file

Use `/v1/images/edits` when an edit depends on a reference file. Use `/v1/images/generations` for a new image created from a text prompt.

When reference images make sense

You want the output to stay close to an existing composition, subject, or product shot.
You need edits and variations around one base image instead of a fully fresh generation.
You want to test whether the current image model supports edits instead of plain image generation only.

What changes after upload

  1. 1Send a multipart/form-data request to `/v1/images/edits`.
  2. 2Attach the reference file in `image` and state the requested change in `prompt`.
  3. 3Read the returned `data` item exactly as you would for image generation.

1. Upload a single clear reference

Start with one image that expresses the key composition or subject. A noisy or irrelevant reference makes debugging harder.

2. Keep the first edit request simple

Use a short prompt that clearly describes what should change. Do not combine too many style and structure instructions in the first attempt.

3. Verify that the model supports edits

Some image models support generation but not edits. If upload works but generation fails, check edit support separately.

4. Use the generation endpoint for a new image

Do not attach an image to `/v1/images/generations`; use its JSON request body for text-to-image creation.

Common mistakes

Treating the reference image like a decorative attachment

Once a reference is attached, it changes the request mode. It is not a passive asset sitting next to the prompt.

Using multi-image generation before the edit path is stable

The reliable order is plain single-image generation first, then single-image edit flow, and only after that more complex batches.

Leaving the reference attached and forgetting why the output changed

If the result suddenly starts following an older image, check whether the reference thumbnail is still present.

What to open next

If the edit request times out, go back to the timeout troubleshooting section and treat the edit path separately from plain generation.
If the model is listed but edits still fail, review the article about visible models that fail at call time.
If you want more predictable results, tune aspect ratio and quality only after the first edit request succeeds.
Read Image Edits APIRead Images APIOpen timeout guide
Image API

How to choose the right aspect ratio for image generation

Aspect ratio should follow the destination of the image, not guesswork. Picking the right frame first reduces wasted generations and makes prompt debugging much simpler.

Choose by destination first

Use 1:1 when the image must work as a neutral square asset, such as a grid card or catalog tile.
Use 4:5 or 2:3 when the image is meant for posters, article covers, or vertically cropped feeds.
Use 9:16 for phone-first or story-like layouts where the full frame is tall.
Use 16:9 or 21:9 only when the final output really needs a wide scene, banner, or cinematic crop.

Practical mapping

1:1

Square product cards, generic thumbnails, neutral prompt testing.

4:5

Social posts, editorial portrait crops, marketplace covers.

2:3

Poster-style output, print-like verticals, fashion/editorial drafts.

9:16

Mobile-first layouts, story covers, tall scene compositions.

3:2 / 5:4

Balanced horizontal compositions with less cinematic width.

16:9 / 21:9

Wide scenic shots, banners, cinematic frames, hero imagery.

Pick ratio before changing the prompt

If you change both ratio and prompt complexity at the same time, you will not know what actually caused the visual shift.

Start from the final crop

Work backward from where the image will be used. Do not generate a wide image if the final slot is a phone portrait card.

Use Auto only when the model is still unknown

Auto is useful when you want to check whether the selected model works at all, but it is not a substitute for choosing a production ratio.

Image API

What the quality option actually changes

The quality switch is not a magic beauty filter. It changes the tradeoff between cost, latency, and the chance of getting a stable image result.

Standard

Use this when you are testing prompts, ratios, or model availability for the first time.
It is usually the best baseline for debugging because the request is cheaper and often returns faster.
If even standard quality is unstable, high quality will not fix a model availability problem.

High quality

Use high quality only after the prompt, ratio, and model already behave the way you expect.
Expect a slower response and a higher chance of timeout under weak model service conditions.
High quality plus multi-image generation is the most expensive and least stable combination in a slow route.

Use standard to debug the route

Do not diagnose timeout, budget, or permission issues while also increasing quality. Keep the request simple first.

Upgrade quality after the first acceptable result

Once you have a composition that works, quality becomes an optimization step rather than a debugging variable.

Treat quality as a workflow decision

Standard is for exploration; high quality is for final output when the selected model is already trustworthy.

Image Results

Process and persist returned image data

A successful image response returns result items in `data`. Your application should validate the response, retain the data it needs, and store important assets in its own storage.

Read each result item

URL: retrieve the returned URL promptly and store a durable copy when your product requires one.
Base64: decode and store the payload using your application's normal binary-data handling.
Request context: retain the public model name and prompt when your product needs reproducible work.
Errors: persist the status code and request timestamp, never an API key or authorization header.

Storage responsibilities

Treat response data as an integration result, not as your application's archive.
Use your own object storage and access control for assets that must persist or be shared.
Keep only the data required by your product and applicable privacy policy.

Persist results deliberately

Move important assets to storage controlled by your application before presenting them to end users.

Keep reproducibility data minimal

Store the model alias, prompt, parameters, and request time only when they are necessary for your product.

Do not expose credentials in result flows

Sanitize client logs and support tickets so API keys and Authorization headers never enter your stored records.

Authentication

Use one key standard across every public endpoint

Send an XVAPI API key only from a trusted server-side environment. Do not embed it in browser code, mobile binaries, or public repositories.

Key scope

Bind keys to package permissions, wallet rules, and request logs.

Header rule

Every public endpoint uses the same Bearer key format. Send the key only from your application's trusted environment.

API Keys

Treat customer API keys as your public contract

Applications need an XVAPI key, their current package access, and the public model list returned for that key.

  • Issue customer-facing API keys from your platform and send them only from trusted server-side environments.
  • Restrict keys by package access and optional model allow-lists when needed.
  • Revoke leaked or temporary keys immediately and re-issue a new key instead of reusing credentials.

Key usage pattern

Use the same customer-facing API key across the public model catalog, chat, embedding, image, and transcription endpoints.

Authorization: Bearer YOUR_XVAPI_API_KEY
Conventions

Keep the public API stable over time

Single public base URL

Expose one stable API domain so every client integration stays predictable.

Customer-owned API keys

Issue your own keys and bind them to balance, package permissions, and request logs.

Stable public model aliases

Keep public model names stable so clients and automation can keep working over time.

GET/v1/models

Models

Return the current public model catalog that the caller can actually use under their package and API key rules.

Public endpoint

Request Notes

  • This endpoint already filters by account access, API key model allow-list, disabled pricing items, and currently available model entries.
  • Use it before building model pickers or caching a catalog on the client side.
  • Metadata includes billing type, label, and the public usage context for the alias.
Request Example
curl $BASE_URL/models \
  -H "$AUTH_HEADER"
Response Shape
{
  "object": "list",
  "data": [
    {
      "id": "gpt-4.1-mini",
      "object": "model",
      "root": "gpt-4.1-mini",
      "metadata": {
        "label": "GPT-4.1 Mini",
        "billing_type": "token"
      }
    }
  ]
}

Public contract

Use these fields and limits as the public integration boundary.

FieldLocationRequiredTypeDescription / constraints
This endpoint does not require a request body.

Headers

AuthorizationBearer token issued by XVAPI.

Response notes

  • Responses use JSON unless the endpoint explicitly documents a streaming or multipart flow.
  • The list is already filtered by the caller's account and API key access.
  • Image models may include metadata.image_generation with supported sizes, qualities, and native 4K support.

Retry guidance

  • Retry 429 only after applying backoff. When Retry-After is present, wait at least that many seconds.
  • Do not blindly retry 400, 401, 402, or 403 responses; fix the request, key, balance, or access rule first.
  • A 502/503 may be temporary, but retry with bounded exponential backoff and keep the same public model name.
POST/v1/chat/completions

Chat Completions

Classic OpenAI-compatible conversational entry for most SDKs and legacy integrations.

Public endpoint

Request Notes

  • Use when your client already targets OpenAI chat-completions semantics.
  • Supports stable public model names across your integrations.
  • Billing and request logs are recorded together for each request.
Request Example
{
  "model": "gpt-4.1-mini",
  "messages": [
    { "role": "system", "content": "You are helpful." },
    { "role": "user", "content": "List three launch checks." }
  ],
  "temperature": 0.6,
  "stream": false
}
Response Shape
{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "model": "gpt-4.1-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "1. Verify wallet balance..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 62,
    "total_tokens": 90
  }
}

Public contract

Use these fields and limits as the public integration boundary.

FieldLocationRequiredTypeDescription / constraints
modelJSON bodyYesstringStable public model alias.
messagesJSON bodyYesarrayNon-empty messages array with role and content values.
temperatureJSON bodyNonumberSampling control forwarded to the selected model.
max_tokensJSON bodyNointegerMaximum number of output tokens the model may generate.
streamJSON bodyNobooleanWhen true, returns an SSE stream.
reasoning_effortJSON bodyNostringOptional reasoning effort hint for models that support it.

Headers

AuthorizationBearer token issued by XVAPI.
Content-TypeUse application/json for JSON request bodies.

Response notes

  • Responses use JSON unless the endpoint explicitly documents a streaming or multipart flow.
  • Non-stream responses keep the chat.completion shape with choices and usage.
  • Streaming responses are server-sent events; consume chunks until the stream closes.

Retry guidance

  • Retry 429 only after applying backoff. When Retry-After is present, wait at least that many seconds.
  • Do not blindly retry 400, 401, 402, or 403 responses; fix the request, key, balance, or access rule first.
  • A 502/503 may be temporary, but retry with bounded exponential backoff and keep the same public model name.
POST/v1/responses

Responses

Unified response surface for newer OpenAI SDKs and workflows that want one modern output object.

Public endpoint

Request Notes

  • Preferred for new clients that already use the Responses API shape.
  • Supports simpler text generation and unified output parsing.
  • Uses the same API key and billing rules as every other public endpoint.
Request Example
{
  "model": "gpt-4.1-mini",
  "input": "Write a short release note for a new model launch."
}
Response Shape
{
  "id": "resp_xxx",
  "object": "response",
  "model": "gpt-4.1-mini",
  "output_text": "We added a new model...",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 48,
    "total_tokens": 60
  }
}

Public contract

Use these fields and limits as the public integration boundary.

FieldLocationRequiredTypeDescription / constraints
modelJSON bodyYesstringStable public model alias.
inputJSON bodyYesstring | object | arrayInput content for the requested response.
instructionsJSON bodyNostringOptional instruction text.
max_output_tokensJSON bodyNointegerMaximum output token budget.
streamJSON bodyNobooleanWhen true, returns a streamed response.
reasoning.effortJSON bodyNostringOptional reasoning effort hint.
reasoning_effortJSON bodyNostringCompatibility alias for reasoning.effort.
metadataJSON bodyNoobjectOptional caller metadata.
toolsJSON bodyNoarrayOptional tool definitions forwarded to the selected model.

Headers

AuthorizationBearer token issued by XVAPI.
Content-TypeUse application/json for JSON request bodies.

Response notes

  • Responses use JSON unless the endpoint explicitly documents a streaming or multipart flow.
  • The public response uses the Responses-compatible object returned by the selected model service.

Retry guidance

  • Retry 429 only after applying backoff. When Retry-After is present, wait at least that many seconds.
  • Do not blindly retry 400, 401, 402, or 403 responses; fix the request, key, balance, or access rule first.
  • A 502/503 may be temporary, but retry with bounded exponential backoff and keep the same public model name.
POST/v1/embeddings

Embeddings

Vector generation for semantic search, RAG indexing, reranking preparation, and retrieval workflows.

Public endpoint

Request Notes

  • Send one string or a list of strings in input.
  • Embedding requests are billed through the same wallet and usage records.
  • Best used with stable public model names.
Request Example
{
  "model": "text-embedding-3-small",
  "input": [
    "xvapi gateway",
    "wallet settlement flow"
  ]
}
Response Shape
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.012, -0.074, ...]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 14,
    "total_tokens": 14
  }
}

Public contract

Use these fields and limits as the public integration boundary.

FieldLocationRequiredTypeDescription / constraints
modelJSON bodyYesstringStable public embedding model alias.
inputJSON bodyYesstring | string[]One text value or a list of text values.
encoding_formatJSON bodyNostringOptional embedding encoding format.
dimensionsJSON bodyNointegerOptional output dimensions when supported by the model.

Headers

AuthorizationBearer token issued by XVAPI.
Content-TypeUse application/json for JSON request bodies.

Response notes

  • Responses use JSON unless the endpoint explicitly documents a streaming or multipart flow.
  • The response contains one embedding item per input value and usage token counts.

Retry guidance

  • Retry 429 only after applying backoff. When Retry-After is present, wait at least that many seconds.
  • Do not blindly retry 400, 401, 402, or 403 responses; fix the request, key, balance, or access rule first.
  • A 502/503 may be temporary, but retry with bounded exponential backoff and keep the same public model name.
POST/v1/images/generations

Image Generations

Public image generation endpoint with your own pricing, logs, and available model catalog.

Public endpoint

Request Notes

  • Use for text-to-image generation from the same public API surface.
  • Image requests consume balance from the same wallet system.
  • Keep image model names stable for clients and automation.
Request Example
{
  "model": "gpt-image-1",
  "prompt": "A futuristic API operations dashboard in soft blue lighting",
  "size": "1024x1024"
}
Response Shape
{
  "created": 1712345678,
  "data": [
    {
      "url": "https://api.xvapi.com/images/req_xxx.png"
    }
  ]
}

Public contract

Use these fields and limits as the public integration boundary.

FieldLocationRequiredTypeDescription / constraints
modelJSON bodyYesstringPublic image model alias.
promptJSON bodyYesstringText description for the generated image.
sizeJSON bodyNostringRequested canvas size.Must be listed in the selected model's supported_sizes metadata.
qualityJSON bodyNostringRequested image quality or resolution tier.Use auto, low, medium, high, 1k, 2k, or 4k; the selected model still decides what is available.
nJSON bodyNointegerNumber of images to generate.Integer from 1 to 4; defaults to 1.
response_formatJSON bodyNostringPreferred image result encoding.Use a format supported by the selected model. Results may contain a URL or base64 payload.
userJSON bodyNostringOptional caller-provided user identifier.

Headers

AuthorizationBearer token issued by XVAPI.
Content-TypeUse application/json for JSON request bodies.

Response notes

  • Responses use JSON unless the endpoint explicitly documents a streaming or multipart flow.
  • The data array contains the generated image results. Each result may expose a URL or a base64 payload depending on the selected model and response_format.

Retry guidance

  • Retry 429 only after applying backoff. When Retry-After is present, wait at least that many seconds.
  • Do not blindly retry 400, 401, 402, or 403 responses; fix the request, key, balance, or access rule first.
  • A 502/503 may be temporary, but retry with bounded exponential backoff and keep the same public model name.
POST/v1/images/edits

Image Edits

Image editing endpoint for reference-image workflows. Use multipart form-data when the request includes an input image.

Public endpoint

Request Notes

  • Use this endpoint when the client uploads a reference image and wants the model to edit or transform it.
  • Submit multipart form-data with model, prompt, and image fields.
  • Edits use the same API key, model access, budget, wallet reservation, and request logging rules as image generation.
Request Example
curl $BASE_URL/images/edits \
  -H "$AUTH_HEADER" \
  -F model="gpt-image-1" \
  -F prompt="Turn this product photo into a clean catalog image" \
  -F image="@reference.png" \
  -F size="1024x1024"
Response Shape
{
  "created": 1712345678,
  "data": [
    {
      "url": "https://api.xvapi.com/images/edit_req_xxx.png"
    }
  ]
}

Public contract

Use these fields and limits as the public integration boundary.

FieldLocationRequiredTypeDescription / constraints
modelmultipartYesstringPublic image edit model alias.
promptmultipartYesstringInstruction describing the requested edit.
imagemultipartYesfileReference image uploaded with the request.PNG, JPEG, or WebP only; maximum 8 MB; the file signature must match its MIME type.
sizemultipartNostringRequested output size.Must be supported by the selected model.
qualitymultipartNostringRequested output quality or resolution tier.The selected model must support the requested tier.
nmultipartNointegerNumber of edited images.Integer from 1 to 4; defaults to 1.
response_formatmultipartNostringPreferred edited-image result encoding.Use a format supported by the selected model.
usermultipartNostringOptional caller-provided user identifier.

Headers

AuthorizationBearer token issued by XVAPI.
Content-TypeUse multipart/form-data; let the client generate the boundary.

Response notes

  • Responses use JSON unless the endpoint explicitly documents a streaming or multipart flow.
  • The data array contains edited image results and may expose URL or base64 output according to the selected model.

Retry guidance

  • Retry 429 only after applying backoff. When Retry-After is present, wait at least that many seconds.
  • Do not blindly retry 400, 401, 402, or 403 responses; fix the request, key, balance, or access rule first.
  • A 502/503 may be temporary, but retry with bounded exponential backoff and keep the same public model name.
POST/v1/audio/transcriptions

Audio Transcriptions

Speech-to-text transcription endpoint for uploaded audio files with the same auth and billing flow.

Public endpoint

Request Notes

  • Current public audio entry focuses on transcription workflows.
  • Upload multipart form-data with file and model fields.
  • Requests are logged and billed under the same customer account.
Request Example
curl $BASE_URL/audio/transcriptions \
  -H "$AUTH_HEADER" \
  -F file="@meeting.mp3" \
  -F model="gpt-4o-mini-transcribe"
Response Shape
{
  "text": "Today we reviewed the gateway release checklist..."
}

Public contract

Use these fields and limits as the public integration boundary.

FieldLocationRequiredTypeDescription / constraints
modelmultipartYesstringPublic transcription model alias.
filemultipartYesfileAudio file to transcribe.Use a file format accepted by the selected transcription model. Start with a small file when integrating a new model.
languagemultipartNostringOptional language hint.
promptmultipartNostringOptional context or vocabulary hint.
response_formatmultipartNostringRequested transcription response format.Use a value supported by the selected transcription model.
temperaturemultipartNonumberOptional transcription sampling control.

Headers

AuthorizationBearer token issued by XVAPI.
Content-TypeUse multipart/form-data; let the client generate the boundary.

Response notes

  • Responses use JSON unless the endpoint explicitly documents a streaming or multipart flow.
  • The normalized public response contains the transcribed text under text.

Retry guidance

  • Retry 429 only after applying backoff. When Retry-After is present, wait at least that many seconds.
  • Do not blindly retry 400, 401, 402, or 403 responses; fix the request, key, balance, or access rule first.
  • A 502/503 may be temporary, but retry with bounded exponential backoff and keep the same public model name.
Model Fields

Understand the public fields returned by /v1/models

The public model catalog is the contract your clients should build against. Use stable aliases and inspect metadata before enabling optional model-specific parameters.

FieldTypeMeaning
idstringStable public model alias used by clients.
objectstringAlways `model` for each item in the list.
rootstringThe canonical alias root exposed publicly.
metadata.labelstringHuman-readable model name for UI display.
metadata.billing_typestringHow the model is billed on your platform.
Model Catalog

Public model names should stay stable

Clients should integrate against the public model catalog. Resolve a model from `/v1/models` before enabling it in an application.

What customers see

gpt-4.1-minigpt-image-1text-embedding-3-smallgpt-4o-mini-transcribe

What the platform can adjust safely

  • Model availability by region and plan
  • Availability and retry policy
  • Pricing adjustments and package permissions
Streaming

Streaming support is endpoint-specific

XVAPI does not expose the same streaming behavior on every endpoint. Document the real surface clearly so customer SDKs behave predictably.

Responses stream

Use `stream: true` on `/v1/responses` when your client expects SSE output. XVAPI keeps reservation, settlement, and tracing consistent across the stream lifecycle.

Responses stream example
{
  "model": "gpt-4.1-mini",
  "input": "List the launch checks step by step.",
  "stream": true
}

Current public rule

Chat Completions supports streaming

Use `stream: true` when you want SSE output on `/v1/chat/completions`. XVAPI keeps reservation, settlement, and tracing consistent across the stream lifecycle.

Recommended rule: use `/v1/responses` for modern response-shaped clients, and keep `/v1/chat/completions` for classic SDK compatibility.

Billing & Wallet

Public billing should follow your own wallet system

A reliable API business needs clear wallet semantics: reserve, settle, release, and trace every request back to a log.

Pre-check

Verify balance and package access before the request starts.

Reserve

Create a customer-facing balance hold when needed.

Settle

Write final billing after usage is known.

Trace

Link every charge to a request log and wallet event.

Limits & Budgets

Every request also passes rate, package, and budget checks

Public requests are subject to rate limits, model access control, package rules, wallet pre-reservation, and user budget policies before final settlement.

Rate limit

Per-account and per-key limits are checked before model execution.

Model access

Package rules and API key model allow-lists both affect what the caller can use.

Budget policy

Estimated request cost is checked against user budget policy before reservation.

Reservation flow

Wallet and key budgets reserve first, then settle or release after the model result returns.

Troubleshooting

Why image generation times out and where to check first

Image generation can take longer than text requests. Handle timeout and availability errors by status code, then retry only the failures that are documented as transient.

Safe recovery sequence

  1. 1Record the public endpoint, model alias, status code, and request time. Do not record API keys or Authorization headers.
  2. 2For 429, honor Retry-After when present before retrying.
  3. 3For 502 or 503, retry with bounded exponential backoff and keep the request idempotent where possible.
  4. 4For 400, 401, 402, or 403, correct the request, credentials, balance, or access before sending it again.

When to contact support

The same 5xx response persists after a bounded retry sequence.
You need help interpreting a request result after removing API keys, authorization headers, and personal data.
Include the endpoint, public model alias, status code, and request time in the support request.
For a new image integration, reduce the first request to one image and a documented size before adding options.

Bounded retries only

Set a small retry limit and exponential delay so temporary errors do not create duplicate cost or overload your application.

Do not retry client errors

Fix 400, 401, 402, and 403 responses before sending another request. Repeating the same request will not resolve them.

Build a minimal reproduction

For image requests, reproduce an issue with one image, one public alias, and documented parameters before adding complexity.

Troubleshooting

Why a model can appear in the list but still fail at call time

Model visibility and model availability are not the same thing. A model name in `/v1/models` is only one part of the public contract.

What “visible” usually proves

The public model catalog returned that model name through `/v1/models`.
The public catalog still exposes that alias.
The caller can see the model entry in a selector or list.

What “callable” still depends on

The current key is actually allowed to use that model.
Package rules, allow-lists, wallet, and budget checks all let the request continue.
The public alias still points to a valid model configuration.
The selected model service can answer a normal request instead of only appearing in the catalog.

Recommended debug order

  1. 1Confirm that the current key can still list at least one usable model through your own `/v1/models` surface.
  2. 2Check whether the failed model is blocked by package rules, allow-lists, or wallet / budget policy.
  3. 3Verify that the public alias still points to the intended model instead of a stale configuration.
  4. 4If the model is visible but still fails, send one small normal request before trying more complex parameters.
Errors

Explain failures in a way support can act on

CodeMeaning
400Bad request shape, missing fields, invalid JSON, or unsupported parameter combinations.
401Missing or invalid API key. Always verify the Bearer token first.
402Insufficient wallet balance or the current billing rule denied the request.
403Your account, package, or model permissions do not allow this request.
429The current account or API key has hit a rate or concurrency limit.
500Temporary service error. Record the request time and model, then contact support if the error continues.
502/503A requested capability is temporarily unavailable. Retry later with bounded exponential backoff.
400 · Missing required fields
{
  "error": {
    "message": "model and messages are required"
  }
}
401 · Invalid API key
{
  "error": {
    "message": "Invalid API key"
  }
}
402

Insufficient balance

{
  "error": {
    "message": "Insufficient wallet balance"
  }
}
429

Rate limit hit

{
  "error": {
    "message": "Rate limit exceeded"
  }
}
403

Model not allowed

{
  "error": {
    "message": "Model not allowed for current package"
  }
}
503

Image generation temporarily unavailable

{
  "error": {
    "message": "Image generation is temporarily unavailable. Please retry or choose another model."
  }
}

Retry policy

Error handling by category

A status code alone is not enough. Follow the category-specific action before deciding whether to retry.

400Do not retry

Request validation

The request body is malformed, missing a required field, or asks for an unsupported option.

Action: Fix the request shape or parameter before sending it again.

401/402/403Do not retry

Authentication, balance, or access

The key, wallet, package, budget policy, or model access rule stopped the request.

Action: Fix the credential, balance, package, budget, or model permission first.

429Retry after backoff

Rate or concurrency limit

The account or API key has reached a request limit. The platform may include Retry-After.

Action: Wait, honor Retry-After when present, then retry with bounded backoff.

500Conditional

Platform error

The platform could not complete the request after its normal checks.

Action: Do not loop aggressively. Check the request time, model, and support logs.

502/503Conditional

Temporary model service failure

The selected model service may be unavailable, degraded, or timed out.

Action: Retry with bounded exponential backoff and keep the same public model alias.

FAQ & Support

Most support issues come down to billing, limits, or model access

Which API domain should my application call?

Use the public Base URL shown in this document together with an API key issued for your XVAPI account.

How should pricing be explained?

Explain wallet balance, model unit pricing, and settlement rules clearly from the customer perspective.

What should support check first when a call looks wrong?

Request logs, wallet events, model name, request time, and whether the problem is billing or latency.

Can a public model name remain stable when services change?

Yes. Keep the public model name stable so clients do not need to change their integration.