One More Shot API

Getting started

1. Create a One More Shot account and make your first purchase. Beta API access must also be enabled for your account.
2. Open Settings → API in the app and create an API key.
3. Copy the key immediately: it is shown only once at creation.

Authentication

Authenticate every request by passing your API key as a Bearer token in the Authorization header. Keys look like oms_live_….

curl https://api.onemoreshot.ai/v1/account \
  -H "Authorization: Bearer oms_live_..."

Rate limits

Requests are rate limited per key — 60 requests per minute by default. When you exceed the limit the API responds with 429 rate_limit_exceeded; wait a full Retry-After interval (currently 60 seconds) before retrying. Reads and cancellation requests count too; the limit uses calendar-minute windows. If you need higher limits for production traffic, contact us.

Idempotency & queued work

Send an Idempotency-Key on every new POST: 1–128 printable non-space ASCII characters. Reuse the same key and identical body after a timeout. Keys are scoped to the account and operation for 24 hours. Replays return the existing job with 202 and Idempotency-Replayed: true; the current status and charge may have changed. Different input with the same key returns 409. Without a key, retries can create separate jobs and charges. The optional idempotency_key body field is also accepted; if both forms are provided, they must match.

A new 202 response means queued admission, not successful media validation or a completed charge. Inspect GET and signed webhooks for asynchronous failures such as insufficient_credits, invalid media or provider errors. Keep the job ID when a client times out; do not submit a new job to check progress. API responses specify Cache-Control: private, no-store. Poll every 15–30 seconds and honor Retry-After.

Errors

Errors always use the same JSON envelope, with a machine-readable code and a human-readable message:

{
  "error": {
    "code": "invalid_request",
    "message": "song_url is required."
  }
}

Pricing

API calls spend tokens from your One More Shot balance — the same tokens you buy in the app. New jobs are queued with zero initial charge. Workers validate media and balance, then charge before provider execution. Invalid media or insufficient tokens fails the job asynchronously without a charge. Charged failures and confirmed cancellations are refunded. Rates below are defaults; configured rates may differ. Video cost is measured seconds × rate, rounded up: 180 seconds of basic lyric video costs 5,940 tokens.

Returns your current token balance and the limits of the key making the request. Useful for checking available credits before dispatching work.

{
  "credits": 4200,
  "scopes": ["lyric_videos", "narrative_videos"],
  "rate_limit_rpm": 60,
  "webhook_secret": "3f1a…9c"
}

Transcribe a song into time-coded lyric segments — the same segments used to drive lyric video generation. Present them to your users for review and editing before generating the final video.

Cost: 5 tokens per song, refunded automatically if the transcription fails.

Request body

curl -X POST https://api.onemoreshot.ai/v1/lyric-videos/transcriptions \
  -H "Authorization: Bearer oms_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
    "song_url": "https://your-cdn.com/song.mp3",
    "trim_start": 0,
    "trim_end": 60
  }'

{
  "id": "aBc123XyZ",
  "status": "processing",
  "credits_charged": 0
}

Transcription is queued; timing depends on queue and provider load. Poll GET /lyric-videos/transcriptions/{id} until status becomes completed or failed.

Returns the status of a transcription job. When completed, the response includes the detected language and the time-coded segments with per-word timings.

{
  "id": "aBc123XyZ",
  "status": "completed",
  "credits_charged": 5,
  "credits_refunded": 0,
  "language": "en",
  "segments": [
    {
      "text": "First line of the song",
      "start": 8.5,
      "end": 10.6,
      "duration": 2.1,
      "wordCount": 5,
      "timedWords": [
        { "text": "First", "start": 8.5, "end": 8.9 }
      ]
    }
  ],
  "error": null,
  "created_at": "2026-01-01T12:00:00.000Z",
  "completed_at": "2026-01-01T12:00:14.000Z"
}

Turn a song into a full lyric video. Optionally pass segments from the transcription endpoint (edited or not) to control the displayed lyrics; without them the song is transcribed automatically as part of the generation.

Cost: priced per second of audio — we probe the song's real duration server-side, so the charge always matches the audio you send. Refunded automatically if the generation fails.

Request body

Segment text is limited to 10,000 characters. Duration must equal end minus start within 0.05 seconds; wordCount is a non-negative integer and timedWords has at most 1,000 entries per segment. Media-dependent validation happens after admission. Request JSON is limited to 1 MB.

Style presets

style_preset accepts exactly one of these keys — any other value is rejected with a 400 invalid_request.

curl -X POST https://api.onemoreshot.ai/v1/lyric-videos \
  -H "Authorization: Bearer oms_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
    "song_url": "https://your-cdn.com/song.mp3",
    "quality": "basic",
    "aspect_ratio": "9:16",
    "song_genre": "pop"
  }'

{
  "id": "dEf456UvW",
  "status": "processing",
  "credits_charged": 0
}

Rendering is queued. Initial admission has no measured duration or charge; these appear after successful preparation. Poll every 15–30 seconds or use webhooks; queue/provider delays vary and a client timeout does not cancel the job. Poll GET /lyric-videos/{id} until status becomes completed or failed or canceled.

Returns the status of a lyric video job. When completed, the response includes the final video and thumbnail URLs.

{
  "id": "dEf456UvW",
  "status": "completed",
  "credits_charged": 5940,
  "credits_refunded": 0,
  "duration_seconds": 180,
  "video_url": "https://storage.googleapis.com/.../final.mp4",
  "thumbnail_url": "https://storage.googleapis.com/.../thumb.jpg",
  "error": null,
  "created_at": "2026-01-01T12:00:00.000Z",
  "completed_at": "2026-01-01T12:07:41.000Z"
}

Cancel a queued video immediately, without charge, before a worker first claims it for media preparation. Cancellation and that claim are checked atomically; if cancellation wins, the job cannot start or charge. Once preparation has started (including retries and waiting for the next generation task), the configured waiting period from job creation applies (60-minute fallback), independently of the displayed ETA. Earlier requests return 409 not_cancellable_yet with Retry-After in seconds. An eligible request is queued and returns 202 with cancellation_requested: true. Poll GET or wait for job.canceled to confirm the canceled status and full refund of charged tokens; completion can win the race. Repeating DELETE after confirmed cancellation returns 204 with no body. Other terminal states return 409 not_cancellable. Transcription has no public cancellation endpoint.

curl -X DELETE https://api.onemoreshot.ai/v1/lyric-videos/dEf456UvW \
  -H "Authorization: Bearer oms_live_..."

{ "id": "dEf456UvW", "status": "processing", "cancellation_requested": true }

Webhooks

Instead of polling, pass a webhook_url (https only) in the body of POST /lyric-videos or POST /lyric-videos/transcriptions. When the job completes, fails or is canceled, we POST its terminal status and result, charges/refunds, error and timestamps, plus a type field.

Events & headers

POST https://your-server.com/oms-webhook
Content-Type: application/json
X-OMS-Event: job.completed
X-OMS-Delivery: dEf456UvW
X-OMS-Signature: sha256=6ac1…e2

{
  "id": "dEf456UvW",
  "type": "lyric_video",
  "status": "completed",
  "credits_charged": 5940,
  "credits_refunded": 0,
  "duration_seconds": 180,
  "video_url": "https://storage.googleapis.com/.../final.mp4",
  "thumbnail_url": "https://storage.googleapis.com/.../thumb.jpg",
  "error": null,
  "created_at": "2026-01-01T12:00:00.000Z",
  "completed_at": "2026-01-01T12:07:41.000Z"
}

Verifying signatures

Your webhook secret is created automatically with your first webhook job and returned by GET /account as webhook_secret. Compute an HMAC-SHA256 of the raw request body and compare it to X-OMS-Signature — reject the request if they differ.

const crypto = require('crypto');
const express = require('express');
const app = express();

// Verify against the RAW request body — the exact bytes we signed.
app.post('/oms-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.OMS_WEBHOOK_SECRET) // from GET /account
    .update(req.body)
    .digest('hex');
  const signature = req.headers['x-oms-signature'] || '';

  const actualBytes = Buffer.from(signature, 'utf8');
  const expectedBytes = Buffer.from(expected, 'utf8');
  const valid = actualBytes.length === expectedBytes.length &&
    crypto.timingSafeEqual(actualBytes, expectedBytes);
  if (!valid) return res.status(401).end();

  const job = JSON.parse(req.body);
  // Dedupe on req.headers['x-oms-delivery'] (equals job.id).
  console.log(job.status, job.video_url);
  res.status(200).end();
});

Delivery & retries

Respond with any 2xx within 10 seconds. Normally there are up to three total HTTP attempts (initial delivery plus two retries). Webhooks are best-effort; keep polling available as a fallback. Retries and crash recovery can produce duplicates: persistently deduplicate by X-OMS-Delivery before applying side effects, and acknowledge duplicates with 2xx.

Support

The API is in beta and evolving quickly. For questions, higher rate limits or volume pricing, reach out via the in-app support chat or our help center.