Get the credit balance

About

Call this before you start an analysis or an export, to know whether the account can pay for it. remaining is what a charge can use right now, as long as planRequired is false: this month's plan credits first, then the top-up. Through the API, the plan credits and the top-up are spent only on the Creator and Studio plans. On any other plan a call through the API spends only the API bonus, and a charge the bonus cannot pay answers PLAN_REQUIRED. The plan credits start again from included on the 1st of each month (UTC) and are not carried over. Top-up credits you bought do not expire. Credits that the GPT-Video app granted to a new account without a purchase expire after a set number of days and are spent only in the app. planRequired is true when the account must choose a plan in the GPT-Video app before it can spend its credits. The API bonus is shown apart, in bonus, and is not part of remaining: while it is active, a call through the API spends the bonus first, even when planRequired is true. Exports, Editor Assistant turns, tool runs and fake text scripts have daily limits, shown in dailyLimits. To see how the balance moved, call list_ledger_entries (GET /v1/credits/ledger).

Example use

Before it works through its queue each night, a script on a Studio account reads remaining and the exports left today in dailyLimits. Analyses and exports that these numbers cannot cover wait for the next night.

Endpoint

GET https://api.gpt-video.com/v1/credits

• Scope clips:read.
• Rate limit 120 requests a minute for each key and 240 for each account, shared by every read call. See rate limits.
• No Idempotency-Key.

Parameters

This operation takes no parameters.

Request

Check the balance before an analysis.

curl "https://api.gpt-video.com/v1/credits" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY"

const res = await fetch("https://api.gpt-video.com/v1/credits", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

import os

import requests

r = requests.get(
    "https://api.gpt-video.com/v1/credits",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
    },
)
data = r.json()
print(data)

{
  "method": "tools/call",
  "params": {
    "name": "get_credits",
    "arguments": {}
  }
}

Response

A successful call answers HTTP 200.

Fields to check

Response example

{
  "plan": "creator",
  "planRequired": false,
  "credits": {
    "period": "2026-09",
    "periodEndsAt": "2026-10-01T00:00:00.000Z",
    "included": 800,
    "remaining": 1020,
    "remainingFromPlan": 770,
    "topUp": 250
  },
  "bonus": null,
  "dailyLimits": {
    "resetsAt": "2026-09-02T00:00:00.000Z",
    "exports": {
      "limit": 100,
      "used": 1,
      "remaining": 99
    },
    "assistantTurns": {
      "limit": 500,
      "used": 12,
      "remaining": 488
    },
    "toolRuns": {
      "limit": 100,
      "used": 2,
      "remaining": 98
    },
    "fakeTextScripts": {
      "limit": 100,
      "used": 0,
      "remaining": 100
    },
    "assistantTurnsThroughApi": {
      "limit": 100,
      "used": 4,
      "remaining": 96
    }
  }
}

{
  "plan": "free",
  "planRequired": true,
  "credits": {
    "period": "2026-09",
    "periodEndsAt": "2026-10-01T00:00:00.000Z",
    "included": 0,
    "remaining": 0,
    "remainingFromPlan": 0,
    "topUp": 0
  },
  "bonus": {
    "status": "active",
    "granted": 50,
    "remaining": 47,
    "grantedAt": "2026-09-01T08:00:00.000Z",
    "expiresAt": "2026-10-01T08:00:00.000Z",
    "resumesAt": null
  },
  "dailyLimits": {
    "resetsAt": "2026-09-02T00:00:00.000Z",
    "exports": {
      "limit": 5,
      "used": 1,
      "remaining": 4
    },
    "assistantTurns": {
      "limit": 20,
      "used": 1,
      "remaining": 19
    },
    "toolRuns": {
      "limit": 10,
      "used": 0,
      "remaining": 10
    },
    "fakeTextScripts": {
      "limit": 10,
      "used": 0,
      "remaining": 10
    },
    "assistantTurnsThroughApi": null
  }
}

Errors

Every call can also answer these errors. VALIDATION_FAILED, UNKNOWN_PARAMETER, UNAUTHORIZED, SCOPE_MISSING, RATE_LIMITED, INTERNAL, UNAVAILABLE.

Cost

No credits are used.

Related operations

• get_me (GET /v1/me) Get the current key
• list_ledger_entries (GET /v1/credits/ledger) List the credit movements
• estimate_analysis (POST /v1/projects/{projectId}/analyze/estimate) Estimate the credits of an analysis or a build
• add_timeline_clip (POST /v1/projects/{projectId}/timeline/clips) Add a video to an edit

Questions

Which credits are spent first?

Through the API, the API bonus while it is active. Then, on the Creator and Studio plans, this month's plan credits. The top-up is used only for what the plan credits do not cover, and what is left of it stays for the next months. On any other plan the plan credits and the top-up are not spent through the API.

Who can spend through the API after the bonus?

The Creator and Studio plans. An account on any other plan, or on no plan, spends only its API bonus through the API. A charge that would touch the plan credits or the top-up of such an account answers PLAN_REQUIRED. The GPT-Video app is not affected: there the plan works as usual.

Can an account without a plan spend through the API?

Only its API bonus, within the daily limits of the account. Credits that the GPT-Video app granted to a new account without a purchase are spent only in the app, and through the API they do not count.

When do the plan credits start again?

On the 1st of each calendar month at 00:00 UTC, at periodEndsAt. Plan credits left at the end of a month are not carried over.

Is remaining exactly what the next charge can use?

Yes, at the moment of the call, while planRequired is false and, through the API, on the Creator and Studio plans: a charge reads the same balance. Another charge made in between, from the API or from the app, lowers it. While the API bonus is active, a call through the API spends the bonus first and leaves remaining as it is.

Does remaining include the API bonus?

No. remaining is the plan credits and the top-up. The bonus has its own block, bonus, with what is left of it and when it ends.

Which daily limits apply through the API on a plan other than Creator or Studio?

While its API bonus is active, the bonus's: 5 exports, 20 Editor Assistant turns, 10 tool runs and 10 fake text scripts a day, or the account's own limits where they are lower. When the bonus is not active the limits are 0, and these calls are refused. The Creator and Studio plans have their own limits.

View as Markdown