Download src/api/openapi.ts from abc1181/Whisper: direct link, hf CLI and curl.
- Browser
- Download file 22.7 kB
-
https://huggingface.co/spaces/abc1181/Whisper/resolve/main/src/api/openapi.ts
- Command line
-
hf download hf://spaces/abc1181/Whisper/src/api/openapi.ts
-
curl -L -o openapi.ts https://huggingface.co/spaces/abc1181/Whisper/resolve/main/src/api/openapi.ts
22.7 kB
| import { CALLBACK_EVENTS } from "./callbacks.js"; | |
| import { VERSION } from "./version.js"; | |
| export const OPENAPI_TITLE = "Pitlane API"; | |
| export const OPENAPI_VERSION = "1.0.0"; | |
| const jobSchema = { | |
| type: "object", | |
| description: | |
| "Job metadata persisted in meta.json. Provider API keys and webhook secrets are never included.", | |
| properties: { | |
| id: { type: "string" }, | |
| kind: { type: "string", enum: ["video", "clip"] }, | |
| topic: { type: "string" }, | |
| archetype: { type: "string" }, | |
| pacing: { type: "string" }, | |
| platform: { type: "string" }, | |
| status: { | |
| type: "string", | |
| enum: ["queued", "running", "completed", "failed", "cancelled", "unknown"], | |
| }, | |
| createdAt: { type: "string", format: "date-time" }, | |
| completedAt: { type: "string", format: "date-time" }, | |
| noAiAssets: { type: "boolean" }, | |
| retryOf: { type: "string", description: "Original job id when created via /retry." }, | |
| metadata: { type: "object", additionalProperties: true }, | |
| stages: { type: "object", additionalProperties: true }, | |
| videoPath: { type: "string", nullable: true }, | |
| posterPath: { | |
| type: "string", | |
| nullable: true, | |
| description: "Still frame of the finished short.", | |
| }, | |
| runDir: { type: "string", nullable: true }, | |
| source: { | |
| type: "object", | |
| nullable: true, | |
| additionalProperties: true, | |
| description: "Clip jobs: the downloaded source and the window that was fetched.", | |
| }, | |
| clips: { | |
| type: "array", | |
| nullable: true, | |
| description: "Clip jobs: every vertical clip that was cut.", | |
| items: { type: "object", additionalProperties: true }, | |
| }, | |
| score: { type: "object", additionalProperties: true }, | |
| costEstimate: { type: "object", additionalProperties: true }, | |
| actualCost: { type: "object", additionalProperties: true }, | |
| error: { type: "string" }, | |
| links: { $ref: "#/components/schemas/JobLinks" }, | |
| }, | |
| required: ["id", "topic", "status", "createdAt", "stages"], | |
| } as const; | |
| const createJobSchema = { | |
| type: "object", | |
| required: ["topic"], | |
| properties: { | |
| topic: { type: "string", maxLength: 500 }, | |
| archetype: { type: "string" }, | |
| pacing: { type: "string" }, | |
| platform: { type: "string", default: "youtube" }, | |
| dryRun: { type: "boolean", default: false }, | |
| noMusic: { type: "boolean", default: false }, | |
| noVideo: { type: "boolean", default: false }, | |
| noAiAssets: { | |
| type: "boolean", | |
| default: false, | |
| description: | |
| "Disable AI image and AI video generation. Scenes use stock media when available and procedural text cards otherwise.", | |
| }, | |
| direction: { type: "string", description: "Creative direction text (max 10 KB UTF-8)." }, | |
| score: { | |
| type: "object", | |
| additionalProperties: true, | |
| description: "A previously saved DirectorScore to replay instead of generating a new one.", | |
| }, | |
| metadata: { | |
| type: "object", | |
| additionalProperties: true, | |
| description: "Caller-defined metadata stored with the job (max 8 KB JSON).", | |
| }, | |
| idempotencyKey: { | |
| type: "string", | |
| maxLength: 255, | |
| description: "Alternative to the Idempotency-Key header.", | |
| }, | |
| callbackUrl: { | |
| type: "string", | |
| format: "uri", | |
| description: "HTTPS endpoint that receives signed job lifecycle webhooks.", | |
| }, | |
| callbackSecret: { | |
| type: "string", | |
| maxLength: 512, | |
| description: "HMAC-SHA256 signing secret. Never stored in meta.json.", | |
| }, | |
| callbackEvents: { | |
| type: "array", | |
| items: { type: "string", enum: [...CALLBACK_EVENTS] }, | |
| }, | |
| callback: { | |
| type: "object", | |
| properties: { | |
| url: { type: "string", format: "uri" }, | |
| secret: { type: "string" }, | |
| events: { type: "array", items: { type: "string", enum: [...CALLBACK_EVENTS] } }, | |
| }, | |
| required: ["url"], | |
| }, | |
| providers: { | |
| type: "object", | |
| properties: { | |
| llm: { type: "string" }, | |
| tts: { type: "string" }, | |
| image: { type: "string" }, | |
| stock: { type: "string" }, | |
| video: { type: "string" }, | |
| videoModel: { type: "string" }, | |
| music: { type: "string" }, | |
| llmModel: { type: "string" }, | |
| llmFallbackModels: { | |
| type: "array", | |
| items: { type: "string" }, | |
| maxItems: 5, | |
| description: "Ordered backup model IDs tried when the primary model fails.", | |
| }, | |
| llmBaseUrl: { type: "string", format: "uri" }, | |
| llmAuthType: { type: "string", enum: ["auto", "none", "bearer", "custom-header"] }, | |
| llmAuthHeader: { type: "string" }, | |
| searchProvider: { type: "string" }, | |
| }, | |
| }, | |
| keys: { | |
| type: "object", | |
| additionalProperties: { type: "string" }, | |
| description: | |
| "Bring-your-own-key credentials for this job. Sent to the worker through Redis and never written to meta.json.", | |
| }, | |
| }, | |
| } as const; | |
| const errorSchema = { | |
| type: "object", | |
| properties: { error: { type: "string" } }, | |
| required: ["error"], | |
| } as const; | |
| const jobLinksSchema = { | |
| type: "object", | |
| properties: { | |
| self: { type: "string" }, | |
| events: { type: "string" }, | |
| artifacts: { type: "string" }, | |
| video: { type: "string", nullable: true }, | |
| poster: { type: "string", nullable: true }, | |
| clips: { type: "array", nullable: true, items: { type: "string" } }, | |
| clipsIndex: { type: "string", nullable: true }, | |
| score: { type: "string" }, | |
| log: { type: "string" }, | |
| cancel: { type: "string", nullable: true }, | |
| retry: { type: "string", nullable: true }, | |
| }, | |
| } as const; | |
| const createClipSchema = { | |
| type: "object", | |
| required: ["sourceUrl"], | |
| properties: { | |
| sourceUrl: { | |
| type: "string", | |
| format: "uri", | |
| description: | |
| "Any yt-dlp-supported source: YouTube, Twitch, Kick, X, TikTok, or a direct video URL.", | |
| }, | |
| count: { type: "integer", minimum: 1, maximum: 10, default: 3 }, | |
| minSeconds: { type: "number", minimum: 5, maximum: 120, default: 20 }, | |
| maxSeconds: { type: "number", minimum: 10, maximum: 180, default: 60 }, | |
| fit: { | |
| type: "string", | |
| enum: ["blur", "crop"], | |
| default: "blur", | |
| description: "How a landscape source is shaped to 9:16. Blur keeps the whole frame.", | |
| }, | |
| captions: { | |
| type: "boolean", | |
| default: true, | |
| description: "Burn word-timed captions. Turn off when the source already has them.", | |
| }, | |
| hook: { type: "boolean", default: true, description: "Burn the clip's hook line for 3s." }, | |
| title: { type: "string", maxLength: 120 }, | |
| startSeconds: { type: "number", minimum: 0 }, | |
| endSeconds: { type: "number", minimum: 0 }, | |
| liveFromStart: { | |
| type: "boolean", | |
| default: false, | |
| description: "For a live stream, read from the start of the broadcast instead of from now.", | |
| }, | |
| maxSourceMinutes: { | |
| type: "number", | |
| minimum: 1, | |
| maximum: 240, | |
| default: 60, | |
| description: "Hard cap on downloaded source length.", | |
| }, | |
| providers: { type: "object", additionalProperties: true }, | |
| keys: { type: "object", additionalProperties: { type: "string" } }, | |
| metadata: { type: "object", additionalProperties: true }, | |
| idempotencyKey: { type: "string", maxLength: 255 }, | |
| }, | |
| } as const; | |
| const standardErrors = { | |
| "400": { $ref: "#/components/responses/BadRequest" }, | |
| "401": { $ref: "#/components/responses/Unauthorized" }, | |
| "404": { $ref: "#/components/responses/NotFound" }, | |
| "409": { $ref: "#/components/responses/Conflict" }, | |
| } as const; | |
| const jobIdParameter = { | |
| name: "id", | |
| in: "path", | |
| required: true, | |
| schema: { type: "string" }, | |
| } as const; | |
| export interface OpenApiOptions { | |
| serverUrl?: string; | |
| apiKeyRequired?: boolean; | |
| } | |
| /** | |
| * Build the OpenAPI 3.1 description of the REST API. Kept as a pure function so | |
| * it can be tested and served without touching Redis or the filesystem. | |
| */ | |
| export function buildOpenApiDocument(options: OpenApiOptions = {}): Record<string, unknown> { | |
| return { | |
| openapi: "3.1.0", | |
| info: { | |
| title: OPENAPI_TITLE, | |
| version: OPENAPI_VERSION, | |
| description: | |
| "Create and manage OpenReels video generation jobs, stream progress, download artifacts, and receive signed webhooks.", | |
| license: { name: "MIT" }, | |
| }, | |
| servers: [{ url: options.serverUrl ?? "/", description: "This OpenReels server" }], | |
| tags: [ | |
| { name: "System" }, | |
| { name: "Catalog" }, | |
| { name: "Jobs" }, | |
| { name: "Artifacts" }, | |
| { name: "Realtime" }, | |
| ], | |
| components: { | |
| securitySchemes: { | |
| bearerAuth: { type: "http", scheme: "bearer" }, | |
| apiKeyAuth: { type: "apiKey", in: "header", name: "X-API-Key" }, | |
| queryApiKey: { | |
| type: "apiKey", | |
| in: "query", | |
| name: "api_key", | |
| description: "Only for EventSource/media URLs that cannot set headers.", | |
| }, | |
| }, | |
| schemas: { | |
| Job: jobSchema, | |
| JobLinks: jobLinksSchema, | |
| CreateJobRequest: createJobSchema, | |
| CreateClipRequest: createClipSchema, | |
| Error: errorSchema, | |
| }, | |
| responses: { | |
| BadRequest: { | |
| description: "Invalid request", | |
| content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } }, | |
| }, | |
| Unauthorized: { | |
| description: "Missing or invalid API key", | |
| content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } }, | |
| }, | |
| NotFound: { | |
| description: "Resource not found", | |
| content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } }, | |
| }, | |
| Conflict: { | |
| description: "Job state does not allow the operation", | |
| content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } }, | |
| }, | |
| }, | |
| }, | |
| ...(options.apiKeyRequired ? { security: [{ bearerAuth: [] }, { apiKeyAuth: [] }] } : {}), | |
| paths: { | |
| "/api/v1/health": { | |
| get: { | |
| tags: ["System"], | |
| summary: "Health check", | |
| security: [], | |
| responses: { | |
| "200": { | |
| description: "Server health, Redis connectivity, configured key names, and version.", | |
| }, | |
| }, | |
| }, | |
| }, | |
| "/api/v1/openapi.json": { | |
| get: { | |
| tags: ["System"], | |
| summary: "OpenAPI document", | |
| security: [], | |
| responses: { "200": { description: "This document" } }, | |
| }, | |
| }, | |
| "/api/v1/docs": { | |
| get: { | |
| tags: ["System"], | |
| summary: "Interactive API documentation", | |
| security: [], | |
| responses: { "200": { description: "HTML documentation page" } }, | |
| }, | |
| }, | |
| "/api/v1/capabilities": { | |
| get: { | |
| tags: ["System"], | |
| summary: "Server capabilities and limits", | |
| responses: { "200": { description: "Feature flags, provider catalog, and limits" } }, | |
| }, | |
| }, | |
| "/api/v1/stats": { | |
| get: { | |
| tags: ["System"], | |
| summary: "Aggregate job statistics", | |
| responses: { "200": { description: "Job counts and total cost" } }, | |
| }, | |
| }, | |
| "/api/v1/archetypes": { | |
| get: { | |
| tags: ["Catalog"], | |
| summary: "List archetypes", | |
| responses: { "200": { description: "Available visual archetypes" } }, | |
| }, | |
| }, | |
| "/api/v1/platforms": { | |
| get: { | |
| tags: ["Catalog"], | |
| summary: "List platforms", | |
| responses: { "200": { description: "Supported output platforms" } }, | |
| }, | |
| }, | |
| "/api/v1/providers": { | |
| get: { | |
| tags: ["Catalog"], | |
| summary: "List provider keys", | |
| responses: { "200": { description: "Supported provider keys and labels" } }, | |
| }, | |
| }, | |
| "/api/v1/jobs": { | |
| get: { | |
| tags: ["Jobs"], | |
| summary: "List jobs", | |
| parameters: [ | |
| { name: "status", in: "query", schema: { type: "string" } }, | |
| { name: "archetype", in: "query", schema: { type: "string" } }, | |
| { name: "platform", in: "query", schema: { type: "string" } }, | |
| { name: "q", in: "query", schema: { type: "string" } }, | |
| { name: "since", in: "query", schema: { type: "string", format: "date-time" } }, | |
| { name: "until", in: "query", schema: { type: "string", format: "date-time" } }, | |
| { | |
| name: "sort", | |
| in: "query", | |
| schema: { type: "string", enum: ["newest", "oldest"] }, | |
| }, | |
| { name: "limit", in: "query", schema: { type: "integer", minimum: 1, maximum: 100 } }, | |
| { name: "offset", in: "query", schema: { type: "integer", minimum: 0 } }, | |
| ], | |
| responses: { | |
| "200": { | |
| description: "Paginated jobs", | |
| content: { | |
| "application/json": { | |
| schema: { | |
| type: "object", | |
| properties: { | |
| jobs: { type: "array", items: { $ref: "#/components/schemas/Job" } }, | |
| total: { type: "integer" }, | |
| limit: { type: "integer" }, | |
| offset: { type: "integer" }, | |
| hasMore: { type: "boolean" }, | |
| }, | |
| }, | |
| }, | |
| }, | |
| }, | |
| }, | |
| }, | |
| post: { | |
| tags: ["Jobs"], | |
| summary: "Create a job", | |
| parameters: [ | |
| { | |
| name: "Idempotency-Key", | |
| in: "header", | |
| schema: { type: "string", maxLength: 255 }, | |
| description: "Replay-safe job creation.", | |
| }, | |
| ], | |
| requestBody: { | |
| required: true, | |
| content: { | |
| "application/json": { schema: { $ref: "#/components/schemas/CreateJobRequest" } }, | |
| }, | |
| }, | |
| responses: { | |
| "201": { | |
| description: "Job queued", | |
| content: { | |
| "application/json": { schema: { $ref: "#/components/schemas/Job" } }, | |
| }, | |
| }, | |
| "200": { | |
| description: | |
| "Existing job returned for a replayed Idempotency-Key (Idempotency-Replayed: true)", | |
| content: { | |
| "application/json": { schema: { $ref: "#/components/schemas/Job" } }, | |
| }, | |
| }, | |
| ...standardErrors, | |
| }, | |
| }, | |
| }, | |
| "/api/v1/clips": { | |
| post: { | |
| tags: ["Clips"], | |
| summary: "Cut vertical clips from a video or stream", | |
| description: | |
| "Downloads the source, transcribes it, chooses self-contained moments, and renders each one at 1080x1920 with burned captions. Returns a normal job, so progress, cancel, retry and artifacts use the same endpoints.", | |
| parameters: [ | |
| { | |
| name: "Idempotency-Key", | |
| in: "header", | |
| schema: { type: "string", maxLength: 255 }, | |
| }, | |
| ], | |
| requestBody: { | |
| required: true, | |
| content: { | |
| "application/json": { schema: { $ref: "#/components/schemas/CreateClipRequest" } }, | |
| }, | |
| }, | |
| responses: { | |
| "201": { | |
| description: "Clip job queued", | |
| content: { | |
| "application/json": { schema: { $ref: "#/components/schemas/Job" } }, | |
| }, | |
| }, | |
| "200": { | |
| description: "Existing job returned for a replayed Idempotency-Key", | |
| content: { | |
| "application/json": { schema: { $ref: "#/components/schemas/Job" } }, | |
| }, | |
| }, | |
| ...standardErrors, | |
| }, | |
| }, | |
| }, | |
| "/api/v1/jobs/batch": { | |
| post: { | |
| tags: ["Jobs"], | |
| summary: "Create up to 25 jobs in one request", | |
| requestBody: { | |
| required: true, | |
| content: { | |
| "application/json": { | |
| schema: { | |
| type: "object", | |
| properties: { | |
| jobs: { | |
| type: "array", | |
| maxItems: 25, | |
| items: { $ref: "#/components/schemas/CreateJobRequest" }, | |
| }, | |
| }, | |
| required: ["jobs"], | |
| }, | |
| }, | |
| }, | |
| }, | |
| responses: { | |
| "201": { | |
| description: "Created jobs and per-item errors", | |
| content: { | |
| "application/json": { | |
| schema: { | |
| type: "object", | |
| properties: { | |
| jobs: { type: "array", items: { $ref: "#/components/schemas/Job" } }, | |
| errors: { | |
| type: "array", | |
| items: { | |
| type: "object", | |
| properties: { | |
| index: { type: "integer" }, | |
| error: { type: "string" }, | |
| }, | |
| }, | |
| }, | |
| }, | |
| }, | |
| }, | |
| }, | |
| }, | |
| ...standardErrors, | |
| }, | |
| }, | |
| }, | |
| "/api/v1/jobs/{id}": { | |
| get: { | |
| tags: ["Jobs"], | |
| summary: "Get a job", | |
| parameters: [jobIdParameter], | |
| responses: { | |
| "200": { | |
| description: "Job metadata and links", | |
| content: { | |
| "application/json": { schema: { $ref: "#/components/schemas/Job" } }, | |
| }, | |
| }, | |
| ...standardErrors, | |
| }, | |
| }, | |
| delete: { | |
| tags: ["Jobs"], | |
| summary: "Delete a finished job and its artifacts", | |
| parameters: [jobIdParameter], | |
| responses: { | |
| "200": { description: "Job deleted" }, | |
| ...standardErrors, | |
| }, | |
| }, | |
| }, | |
| "/api/v1/jobs/{id}/cancel": { | |
| post: { | |
| tags: ["Jobs"], | |
| summary: "Cancel a queued or running job", | |
| parameters: [jobIdParameter], | |
| responses: { | |
| "200": { description: "Cancellation requested" }, | |
| ...standardErrors, | |
| }, | |
| }, | |
| }, | |
| "/api/v1/jobs/{id}/retry": { | |
| post: { | |
| tags: ["Jobs"], | |
| summary: "Re-run a finished job as a new job", | |
| parameters: [jobIdParameter], | |
| responses: { | |
| "201": { | |
| description: "New job queued", | |
| content: { | |
| "application/json": { schema: { $ref: "#/components/schemas/Job" } }, | |
| }, | |
| }, | |
| ...standardErrors, | |
| }, | |
| }, | |
| }, | |
| "/api/v1/jobs/{id}/events": { | |
| get: { | |
| tags: ["Realtime"], | |
| summary: "Stream job progress with Server-Sent Events", | |
| description: | |
| "Emits job:snapshot, stage:<name>, job:completed, job:failed, and job:cancelled events. Use ?api_key= when the EventSource API cannot set headers.", | |
| parameters: [jobIdParameter], | |
| responses: { "200": { description: "text/event-stream" } }, | |
| }, | |
| }, | |
| "/api/v1/jobs/{id}/artifacts": { | |
| get: { | |
| tags: ["Artifacts"], | |
| summary: "List job artifacts", | |
| parameters: [jobIdParameter], | |
| responses: { | |
| "200": { | |
| description: "Files with sizes, timestamps, content types, and download URLs", | |
| content: { | |
| "application/json": { | |
| schema: { | |
| type: "object", | |
| properties: { | |
| jobId: { type: "string" }, | |
| artifacts: { | |
| type: "array", | |
| items: { | |
| type: "object", | |
| properties: { | |
| path: { type: "string" }, | |
| size: { type: "integer" }, | |
| modifiedAt: { type: "string", format: "date-time" }, | |
| contentType: { type: "string" }, | |
| url: { type: "string" }, | |
| }, | |
| }, | |
| }, | |
| }, | |
| }, | |
| }, | |
| }, | |
| }, | |
| ...standardErrors, | |
| }, | |
| }, | |
| }, | |
| "/api/v1/jobs/{id}/artifacts/{path}": { | |
| get: { | |
| tags: ["Artifacts"], | |
| summary: "Download an artifact", | |
| parameters: [ | |
| jobIdParameter, | |
| { name: "path", in: "path", required: true, schema: { type: "string" } }, | |
| ], | |
| responses: { | |
| "200": { description: "File contents" }, | |
| "403": { description: "Path traversal or symlink rejected" }, | |
| ...standardErrors, | |
| }, | |
| }, | |
| }, | |
| "/api/v1/jobs/{id}/video": { | |
| get: { | |
| tags: ["Artifacts"], | |
| summary: "Download the rendered video", | |
| parameters: [jobIdParameter], | |
| responses: { "200": { description: "MP4 video" }, ...standardErrors }, | |
| }, | |
| }, | |
| "/api/v1/jobs/{id}/score": { | |
| get: { | |
| tags: ["Artifacts"], | |
| summary: "Get the DirectorScore", | |
| parameters: [jobIdParameter], | |
| responses: { | |
| "200": { description: "DirectorScore JSON" }, | |
| ...standardErrors, | |
| }, | |
| }, | |
| }, | |
| "/api/v1/jobs/{id}/log": { | |
| get: { | |
| tags: ["Artifacts"], | |
| summary: "Get the run log", | |
| parameters: [jobIdParameter], | |
| responses: { | |
| "200": { description: "Run log JSON" }, | |
| ...standardErrors, | |
| }, | |
| }, | |
| }, | |
| }, | |
| }; | |
| } | |
| /** Small HTML shell that renders the OpenAPI document with Redoc. */ | |
| export function renderDocsHtml(): string { | |
| return `<!doctype html> | |
| <html lang="en"> | |
| <head> | |
| <meta charset="utf-8" /> | |
| <meta name="viewport" content="width=device-width, initial-scale=1" /> | |
| <title>${OPENAPI_TITLE}</title> | |
| <style>body { margin: 0; padding: 0; }</style> | |
| </head> | |
| <body> | |
| <redoc spec-url="/api/v1/openapi.json"></redoc> | |
| <script src="https://cdn.redoc.ly/redoc/latest/bundled/redoc.standalone.js"></script> | |
| </body> | |
| </html>`; | |
| } | |
| /** Version reported by health and capabilities endpoints. */ | |
| export const API_VERSION = VERSION; | |