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

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

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.