# Code Story video generation

Code Story is available as provider `codestory`, model `codestory/api`, alongside
HeyGen. It creates educational and promotional videos through an asynchronous
workflow at `https://api.thecodeapi.com/v1/codestory`. Use these REST endpoints with your
server-side The-Code API key. Do not send `codestory/api` to chat or Responses.

## Before creating a video

Ask your administrator to activate Code Story, approve pricing and enable
`codestory/api` for your account and API key. Check authenticated `GET /v1/models`
for availability. The gateway stores the provider credential; your application
only needs its The-Code API key. Read `GET /v1/codestory/catalog` for supported
languages, formats and families, and `GET /v1/codestory/estimate` for an estimate.
An estimate neither reserves funds nor guarantees the final cost.

## Create and poll

```bash
curl https://api.thecodeapi.com/v1/codestory/videos \
  -H "Authorization: Bearer $THE_CODE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lesson-001" \
  -d '{"topic":"How compound interest works","duration_s":60,
       "langs":["en"],"formats":["edu_16x9"],"family":"compose","max_usd":10}'
```

Save the returned `id` from the HTTP `202` `codestory.generation` object. The worker
submits the request and tracks the provider. Poll `GET /v1/codestory/videos/{id}`
every 60 seconds using the same key. When `status` is `completed`, download
`files[].content_url` with the same authentication. Downloads are stored privately
by the gateway; they are not public sharing URLs. Files follow project retention.

Creation requires a positive `max_usd` no greater than 1000 and either
`external_id` or `Idempotency-Key`. `external_id` takes precedence. Use exactly
one of `topic` (8–200 characters) or a production `prompt` (at least 40 words).
The `compose` and `2d` families support this form. `promo` and `promo_lesson`
require `brief` instead, and a duration of 15–90 or 30–300 seconds respectively.
Use the endpoint schema for the complete request contract.

## Spending and settlement

`max_usd` limits the video's lifetime **provider cost**, across all continuations.
`max_credits` in the response includes your snapshotted customer uplift; one
credit equals USD 0.01. A USD 10 provider cap with a 20% total uplift requires
1200 customer credits. Creation reserves that full amount before work is queued.
Optional `X-The-Code-Max-Credits` rejects a new reservation above your own credit
ceiling. This is a reservation limit for the operation; increasing a video's cap
on continuation requires more available credits.

Completed, failed and cancelled jobs settle only their final, non-provisional
actual cost and release the unused hold. A stopped video retains its hold.
Provisional or unverified billing remains pending. Continuation bills only cost
not previously settled and keeps the original price for the video's lifetime.
Final billing settles before downloading files, so a download outage does not
keep unused funds reserved. Over-cap or decreasing provider costs require
reconciliation rather than an automatic charge.

## Retry, continue and cancel

After a lost create response, repeat the identical body with the same
idempotency ID. It returns the same local video, even for a failed draft.
A changed body with that ID returns `409`. Do not invent a new ID to retry an
uncertain job. Video IDs and list results are scoped to the creating API key.

To resume a failed or stopped video, `POST /v1/codestory/videos/{id}/continue`
with `{}` or `{"max_usd":12}` to explicitly raise its lifetime cap. Caps cannot
be lowered. Continue is **not idempotent**: after a lost response, poll the video
before doing anything else. The gateway sends each queued continuation once;
an uncertain provider outcome may show `indeterminate` with funds still held.
Contact support for reconciliation; do not automatically start another video.

`POST /v1/codestory/videos/{id}/cancel` requests cancellation and reconciles
any actual cost. Cancellation can take time. `DELETE /v1/codestory/videos/{id}`
is permitted after settlement and removes artifacts while retaining the billing
and idempotency record. A new video requires a new idempotency ID.

## Endpoint reference

| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/v1/codestory/catalog` | Supported choices |
| GET | `/v1/codestory/estimate` | Estimate with duration_s, langs, formats, family |
| POST | `/v1/codestory/videos` | Queue a capped video |
| GET | `/v1/codestory/videos` | Most recent 100 videos for this key |
| GET | `/v1/codestory/videos/{id}` | Progress, cost and files |
| POST | `/v1/codestory/videos/{id}/continue` | Resume, optionally raising the cap |
| POST | `/v1/codestory/videos/{id}/cancel` | Cancel and reconcile cost |
| DELETE | `/v1/codestory/videos/{id}` | Delete settled artifacts |
| GET | `/v1/codestory/videos/{id}/files/{file_id}` | Authenticated download |

A `402` can indicate insufficient credits or a reservation above the caller's
ceiling; `409` indicates conflict, busy or unsettled work, or an invalid cap.
Validation errors use `400` or `422`. Keep the returned video ID and inspect its
`status`, `cost_status`, `error_code` and `error_message`. A worker retry or
provider failure is not permission to make another paid request.

## Discover through MCP

Read `the-code://docs/videos` or use `search_docs` with `Code Story`.
Call `get_endpoint_schema` with `/v1/codestory/videos`; it defaults to POST.
Pass `method: GET` for listing. For `/v1/codestory/videos/{public_id}`, pass
`method: DELETE` for deletion. These placeholders follow the OpenAPI schema.
`get_example` accepts endpoint `/v1/codestory/videos` with cURL, Python or
JavaScript. MCP tools only explain the integration and do not create videos,
continue jobs, reserve credits or expose the provider account balance.
`validate_request` currently covers chat, responses, embeddings and audio,
not video requests. Use the published video schema and REST validation.