> ## Documentation Index > Fetch the complete documentation index at: https://docs.hopscotchlabs.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a video > Create a video job, in OpenAI's Sora shape (`client.videos.create`), and answer the provider's job object. A hold of `seconds` (4 when absent) times the model's per-second rate for the requested `size` is taken before anything is sent to the provider, and stays open until the job ends: a completed job is charged the seconds the provider reports, never above the hold; a failed or provider-confirmed cancelled job is charged nothing; a job not finished three hours after create is charged its full hold. One usage row is written per job, when it settles. The hold is zero on a workspace-owned credential. A model whose rates are duration tiers holds the requested seconds at the tier equal to them, and at the dearest tier when the seconds name none, so a hold never undercharges. A completed job reporting zero seconds releases the hold and records served usage at zero charge; absent or unreadable seconds charge the full hold. Video usage is timestamped when the job settles, so its usage period follows the settled charge. The body may be JSON or multipart/form-data (an `input_reference` image rides in the form) and is capped at 8 MiB; a larger body is refused 413 before any hold. The job belongs to the account that created it: the follow-up paths answer only that account. Listing (`GET /v1/videos`) and remix are not served. Each model accepts only the durations and sizes it publishes: a create naming anything else is refused 400 before anything is held. `GET /v1/models` lists the exact strings this key can call. ## OpenAPI ````yaml /api-reference/openapi.public.json post /v1/videos openapi: 3.0.3 info: title: Hopscotch version: v1 description: >- An OpenAI-compatible inference API. Point an OpenAI client at https://api.hopscotchlabs.ai, give it a Hopscotch API key, and call models across providers on one prepaid balance. Every response, errors included, matches the shape an unmodified OpenAI SDK expects. servers: - url: https://api.hopscotchlabs.ai description: Production security: - customerApiKey: [] tags: - name: Chat description: Chat completions, streamed or not. - name: Models description: What you can call. - name: Completions description: Text completions, streamed or not. - name: Messages description: The Anthropic Messages API, streamed or not. - name: Usage description: What one request recorded and what it cost. - name: Videos description: 'Video jobs: create, poll, download, delete.' paths: /v1/videos: post: tags: - Videos summary: Create a video description: >- Create a video job, in OpenAI's Sora shape (`client.videos.create`), and answer the provider's job object. A hold of `seconds` (4 when absent) times the model's per-second rate for the requested `size` is taken before anything is sent to the provider, and stays open until the job ends: a completed job is charged the seconds the provider reports, never above the hold; a failed or provider-confirmed cancelled job is charged nothing; a job not finished three hours after create is charged its full hold. One usage row is written per job, when it settles. The hold is zero on a workspace-owned credential. A model whose rates are duration tiers holds the requested seconds at the tier equal to them, and at the dearest tier when the seconds name none, so a hold never undercharges. A completed job reporting zero seconds releases the hold and records served usage at zero charge; absent or unreadable seconds charge the full hold. Video usage is timestamped when the job settles, so its usage period follows the settled charge. The body may be JSON or multipart/form-data (an `input_reference` image rides in the form) and is capped at 8 MiB; a larger body is refused 413 before any hold. The job belongs to the account that created it: the follow-up paths answer only that account. Listing (`GET /v1/videos`) and remix are not served. Each model accepts only the durations and sizes it publishes: a create naming anything else is refused 400 before anything is held. `GET /v1/models` lists the exact strings this key can call. operationId: createVideo parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VideoCreateRequest' type: object properties: model: type: string description: >- The model to call. A provider-pinned id, `{provider}/{model}`, is split once on the first slash. A routing-profile slug, `profile/{identifier}`, tries that profile's models in your own order. `unirouter/auto`, or its second spelling `hopscotch/auto`, names whichever route your workspace made its default. A bare model id is refused with 400 and the code `model_id_not_pinned`. `GET /v1/models` lists the exact strings this key can call. example: openai/sora-2 prompt: type: string description: >- Required for text-to-video. A model that renders from an image permits an omitted prompt when `input_reference` is uploaded. example: A paper boat drifting down a rainy street. seconds: type: string description: >- Whole seconds of video, 1 or more, as decimal digits without whitespace, hexadecimal or exponent notation (such as `"8"`); JSON also accepts a positive safe integer. Absent, 4. A hold beyond the safe money range is refused with 400 naming `seconds` and the cap at the matching published rate, before any credit is held. A create naming a duration the model does not publish is refused 400 before anything is held. example: '8' size: type: string description: >- The resolution, such as `"1280x720"`. Required: a create that names none is refused before anything is held. It must have a per-second rate on the model; one without is refused before anything is held. A create naming a size the model does not publish is refused 400 before anything is held. example: 1280x720 input_reference: type: string format: binary description: >- A reference image, sent as a multipart file part under this name. A model that renders from an image only requires it, and with an accepted image reference `prompt` is optional. A model that renders from text only refuses it. Each model accepts only the image forms and sizes it publishes. required: - model - size example: model: openai/sora-2 prompt: A paper boat drifting down a rainy street. seconds: '8' size: 1280x720 multipart/form-data: schema: $ref: '#/components/schemas/VideoCreateRequest' type: object properties: model: type: string description: >- The model to call. A provider-pinned id, `{provider}/{model}`, is split once on the first slash. A routing-profile slug, `profile/{identifier}`, tries that profile's models in your own order. `unirouter/auto`, or its second spelling `hopscotch/auto`, names whichever route your workspace made its default. A bare model id is refused with 400 and the code `model_id_not_pinned`. `GET /v1/models` lists the exact strings this key can call. example: openai/sora-2 prompt: type: string description: >- Required for text-to-video. A model that renders from an image permits an omitted prompt when `input_reference` is uploaded. example: A paper boat drifting down a rainy street. seconds: type: string description: >- Whole seconds of video, 1 or more, as decimal digits without whitespace, hexadecimal or exponent notation (such as `"8"`); JSON also accepts a positive safe integer. Absent, 4. A hold beyond the safe money range is refused with 400 naming `seconds` and the cap at the matching published rate, before any credit is held. A create naming a duration the model does not publish is refused 400 before anything is held. example: '8' size: type: string description: >- The resolution, such as `"1280x720"`. Required: a create that names none is refused before anything is held. It must have a per-second rate on the model; one without is refused before anything is held. A create naming a size the model does not publish is refused 400 before anything is held. example: 1280x720 input_reference: type: string format: binary description: >- A reference image, sent as a multipart file part under this name. A model that renders from an image only requires it, and with an accepted image reference `prompt` is optional. A model that renders from text only refuses it. Each model accepts only the image forms and sizes it publishes. required: - model - size responses: '200': description: >- The provider's video job object (id, status, progress), with external URLs omitted. A recorded job is charged when a terminal status is observed. If the provider returns no readable job id or an id already recorded for that provider, the full hold is charged immediately and usage is recorded under this create request's unique request id. headers: x-hopscotch-served-by: $ref: '#/components/headers/ServedBy' description: >- The full id, "{provider}/{model}", of the model that actually answered: the pinned id when the request named one directly, or the routing-profile chain member that served when the request named a profile. schema: type: string example: openai/gpt-4o-mini x-hopscotch-served-via: $ref: '#/components/headers/ServedVia' description: >- Present, with the value `backup`, when a backup route served this request. Absent on every other response, and never sent with any other value, so a client that has never read it sees nothing change about an ordinary request. The provider named on x-hopscotch-provider and in the body is still the one you asked for. schema: type: string enum: - backup example: backup x-hopscotch-request-id: $ref: '#/components/headers/RequestId' x-request-id: $ref: '#/components/headers/SdkRequestId' x-hopscotch-provider: $ref: '#/components/headers/Provider' x-hopscotch-retry-attempt-count: $ref: '#/components/headers/RetryAttemptCount' x-hopscotch-cache-status: $ref: '#/components/headers/CacheStatus' x-hopscotch-trace-id: $ref: '#/components/headers/TraceId' x-hopscotch-redirected-from: description: >- Present only when a sunset redirect served this request. The retiring model id requested, including a profile member redirected to its successor. schema: type: string example: openai/retiring-model x-hopscotch-served-model: description: >- The successor model that actually answered a sunset redirect, priced and admitted under that model. Present for JSON and streamed replies. schema: type: string example: openai/successor-model content: application/json: schema: $ref: '#/components/schemas/VideoJob' example: id: video_123 object: video model: openai/sora-2 status: queued progress: 0 created_at: 1788998400 size: 1280x720 seconds: '8' '400': description: >- The request cannot be served as sent. `model` and `size` are required, and `seconds` must be a whole number of seconds, 1 or more. A refusal the provider made about this request is relayed with the provider's own status and its own sentence, so a parameter it requires and did not get reads as what it is rather than as a fault on this platform. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_model: summary: No model named value: error: message: >- You must provide a model parameter naming the model to call. It is read to work out what the request could cost before it is sent. type: invalid_request_error param: model code: null request_id: REQUEST_ID missing_size: summary: No size named value: error: message: >- "size" must be a resolution such as "1280x720" for "MODEL_ID". No credit was held and nothing was sent. type: invalid_request_error param: size code: null request_id: REQUEST_ID bad_seconds: summary: Seconds are not a whole number of 1 or more value: error: message: >- "seconds" must be a whole number of seconds, 1 or more, for "MODEL_ID". No credit was held and nothing was sent. type: invalid_request_error param: seconds code: null request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '401': description: >- No key, a scheme other than Bearer, a key of the wrong shape, or a key we reject. An unknown key and a revoked key are answered with one identical message on purpose. A key past its own expiry date is refused here too, with code `key_expired` and a message naming the date. It is checked before the per-minute rate limiter, so an expired key never consumes that allowance. Expired keys are not renewed: create a new one. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: Incorrect API key provided. type: authentication_error param: null code: invalid_api_key request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '402': description: >- The request will not be paid for, and nothing was charged. Code `insufficient_credit` is the workspace being out of credit, which stops every key on it. Code `key_limit_exceeded` is the sending key reaching its own credit limit, which leaves every other key in the workspace serving normally; it is refused before any credit is held, and the message names what that key has settled and holds inside its current window. content: application/json: schema: $ref: '#/components/schemas/Error' examples: insufficient_credit: summary: The workspace is out of credit value: error: message: >- This account has 54 minor units available and the request needs 55 held. type: insufficient_quota param: null code: insufficient_credit request_id: REQUEST_ID key_limit_exceeded: summary: This key is at its own limit value: error: message: >- This key may spend $20.00 in its current window and has $18.40 settled and $1.70 held against that, so a request needing $0.30 more is refused. Nothing was charged for it and no credit was held. The limit belongs to this key alone, so other keys in the workspace are unaffected. This limit resets monthly on UTC calendar windows, so requests are admitted again when the window rolls. It can also be raised or removed on the Keys screen. type: insufficient_quota param: null code: key_limit_exceeded request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '403': description: >- Refused for a setting the caller owns rather than anything about the model, and `code` names which. A key whose account staff have suspended is refused with code `account_suspended`, before any credit is held or any provider is called; contact support, because retrying will not change the answer. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: >- This account is suspended, so it cannot send requests. Contact support. Request id REQUEST_ID. type: permission_error param: null code: account_suspended request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '404': description: >- The model cannot be served, and the two cases are told apart by `code`. `model_not_found` means the id is in no catalog at all, which is what a typo produces, so check the spelling or list what this key can call with `GET /v1/models`. `model_not_available` means the id is catalogued and is not being served right now, either on this endpoint or at all, so retrying later is worth more than changing the request. No provider was called either way. content: application/json: schema: $ref: '#/components/schemas/Error' examples: model_not_found: summary: No model of that id exists value: error: message: >- The model "MODEL_ID" does not exist. Check the spelling, or list the models this key can call with GET /v1/models. type: not_found_error param: null code: model_not_found request_id: REQUEST_ID model_not_available: summary: Known to us, and not being served right now value: error: message: >- The model "MODEL_ID" is not currently available. It is known to this platform and is not being served right now, so retrying later is worth more than changing the request. type: not_found_error param: null code: model_not_available request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '409': description: >- The workflow named by x-hopscotch-workflow-id is archived and takes no new requests. Checked before any hold or provider call. headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '413': description: >- The request body is larger than the 8388608 byte maximum this API accepts, so it was refused at the door. A body that declares its length is refused without a byte being read; one that declares none is read only as far as the ceiling and then abandoned. Nothing was parsed, no credit was held, no model was called and nothing was charged. content: application/json: schema: $ref: '#/components/schemas/Error' examples: payload_too_large: summary: The request body is over the ceiling value: error: message: >- This request body is larger than the 8388608 byte maximum this API accepts. Nothing was read, no model was called and nothing was charged. Send fewer messages, a shorter prompt, or fewer inputs. type: invalid_request_error param: null code: payload_too_large request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '429': description: >- A limit refused the request. `rate_limit_exceeded` is this key's own request rate and carries `Retry-After`. `spend_rate_exceeded` is the account spend rate cap, which counts the credit held for requests rather than the credit they settle at, and carries `Retry-After`. `upstream_rate_limited` is the model's provider rate-limiting the call: nothing about the request is wrong, nothing is charged, and it carries `Retry-After`. headers: Retry-After: schema: type: integer minimum: 1 description: >- Seconds to wait. Present on `rate_limit_exceeded`, `spend_rate_exceeded` and `upstream_rate_limited`. example: 17 x-hopscotch-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limit_exceeded: summary: This key's request rate value: error: message: >- Rate limit reached for this key. Try again in 12 seconds. Request id REQUEST_ID. type: rate_limit_error param: null code: rate_limit_exceeded request_id: REQUEST_ID spend_rate_exceeded: summary: The account spend rate cap value: error: message: >- This account has already reserved 5000 minor units in the last 60 seconds, which is at its ceiling of 5000. Requests are admitted again within 60 seconds of the earliest reservation counted, with nothing to do in the meantime. type: rate_limit_error param: null code: spend_rate_exceeded request_id: REQUEST_ID upstream_rate_limited: summary: The model's provider rate-limited the call value: error: message: >- The provider serving this model is rate-limiting requests right now. Nothing was charged. Retry after the number of seconds in the Retry-After header. Quote the request id if you contact support. type: rate_limit_error param: null code: upstream_rate_limited request_id: REQUEST_ID '500': description: A fault on our side. The request id is the one thing worth keeping. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: >- The server had an error while processing your request. Sorry about that! Quote the request id if you contact support. type: api_error param: null code: null request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '503': description: >- Ours rather than yours, and `code` names the condition. `paused_by_owner` clears only when somebody lifts the pause, so retrying on a timer will not help. `balance_unavailable` (we could not read the balance, so the request was refused rather than served unmetered), `model_not_priceable` and `model_pricing_unreadable` (a model we list could not be priced for this call) and `no_provider_configured` (we are not currently configured to serve this) all clear without you doing anything. content: application/json: schema: $ref: '#/components/schemas/Error' examples: paused_by_owner: summary: Somebody pressed Pause value: error: message: >- Every request on this account is paused, because somebody with access to it pressed Pause in the dashboard. Nothing was charged for this request and no credit was held for it. It is retryable, and it will be refused the same way until the pause is lifted, so retrying on a timer will not clear it. Requests start working again the moment the pause is lifted from the same control, with nothing else to do and nothing to re-create. type: server_error param: null code: paused_by_owner request_id: REQUEST_ID balance_unavailable: summary: We could not read the balance value: error: message: >- Your credit balance could not be checked while this request was running, so it was stopped rather than left unwatched. This is a fault on our side rather than a problem with your account, and it does not mean you are out of credit. Try again shortly. type: server_error param: null code: balance_unavailable request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '504': description: The request ran past the request deadline and was terminated. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: >- This request ran longer than the 540 second limit and was terminated. Reduce the amount of work in one call, or stream the response, and try again. type: server_error param: null code: request_deadline_exceeded request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' security: - customerApiKey: [] servers: - url: https://api.hopscotchlabs.ai description: Production components: schemas: VideoCreateRequest: type: object description: >- Create a video job. The body may be JSON or multipart/form-data; an input_reference image rides in the form. required: - model - size properties: model: type: string description: >- The model to call. A provider-pinned id, `{provider}/{model}`, is split once on the first slash. A routing-profile slug, `profile/{identifier}`, tries that profile's models in your own order. `unirouter/auto`, or its second spelling `hopscotch/auto`, names whichever route your workspace made its default. A bare model id is refused with 400 and the code `model_id_not_pinned`. `GET /v1/models` lists the exact strings this key can call. example: openai/sora-2 prompt: type: string description: >- Required for text-to-video. A model that renders from an image permits an omitted prompt when `input_reference` is uploaded. example: A paper boat drifting down a rainy street. seconds: type: string description: >- Whole seconds of video, 1 or more, as decimal digits without whitespace, hexadecimal or exponent notation (such as `"8"`); JSON also accepts a positive safe integer. Absent, 4. A hold beyond the safe money range is refused with 400 naming `seconds` and the cap at the matching published rate, before any credit is held. A create naming a duration the model does not publish is refused 400 before anything is held. example: '8' size: type: string description: >- The resolution, such as `"1280x720"`. Required: a create that names none is refused before anything is held. It must have a per-second rate on the model; one without is refused before anything is held. A create naming a size the model does not publish is refused 400 before anything is held. example: 1280x720 input_reference: type: string format: binary description: >- A reference image, sent as a multipart file part under this name. A model that renders from an image only requires it, and with an accepted image reference `prompt` is optional. A model that renders from text only refuses it. Each model accepts only the image forms and sizes it publishes. VideoJob: type: object description: >- One video job, as the provider reports it, with external URLs omitted and `model` rewritten to the public id the create returned. Providers report different extra fields; only the fields below are promised. required: - id - object - model - status additionalProperties: true properties: id: type: string description: The job id the create answered. Pass it to the follow-up paths. example: video_123 object: type: string enum: - video model: type: string description: >- The public `provider/model` id the create returned, so a poll names the model exactly as the create did. example: openai/sora-2 status: type: string description: >- Where the job stands. A provider that answers `succeeded` means completed. enum: - queued - in_progress - completed - failed - cancelled - succeeded progress: type: integer description: How far along the provider says the job is, 0 to 100. created_at: type: integer description: When the job was created, in Unix seconds. nullable: true size: type: string description: The requested size, in OpenAI `WIDTHxHEIGHT` spelling. example: 1280x720 seconds: type: string description: >- The seconds of video, as a decimal string. A completed job reports what it rendered; settlement never charges above what the hold covered. example: '8' error: type: object description: >- Present when the job failed: the provider's reason, with a stable `code` and a prose `message`. properties: code: type: string example: video_generation_failed message: type: string Error: type: object description: The error envelope. One top-level `error` key, always, at every status. required: - error additionalProperties: false properties: error: type: object required: - message - type - param - code additionalProperties: false properties: message: type: string description: Prose for a person. It may be reworded, so do not branch on it. type: type: string description: The category an SDK branches on. A closed set. enum: - invalid_request_error - authentication_error - permission_error - not_found_error - rate_limit_error - api_error - insufficient_quota - server_error param: type: string nullable: true description: >- The request field at fault, or null. Present and null rather than absent. code: type: string nullable: true description: The stable machine-readable reason. Branch on this. request_id: type: string description: >- Our id for this request, the same value as the x-hopscotch-request-id header. Quote it when you contact support. headers: ServedBy: description: >- The full id, "{provider}/{model}", of the model that actually answered: the id you pinned, or the member of the routing profile that served. Present on every served reply, streamed or not, which is the only place a streamed request can read it. schema: type: string example: openai/gpt-4o-mini ServedVia: description: >- Present, with the value `backup`, when a backup route served this request. Absent on every other response, and never sent with any other value, so a client that has never read it sees nothing change about an ordinary request. The provider named on x-hopscotch-provider and in the body is still the one you asked for. schema: type: string enum: - backup example: backup RequestId: description: >- Our id for this request. Quote it when you contact support. Present on every response, errors included. schema: type: string SdkRequestId: description: >- The same value as x-hopscotch-request-id, on the header the official OpenAI SDKs surface on their error objects. schema: type: string Provider: description: Which provider answered. schema: type: string RetryAttemptCount: description: How many attempts were made before the response you received. schema: type: string CacheStatus: description: Whether the reply came from cache. schema: type: string TraceId: description: A trace id for this request. schema: type: string securitySchemes: customerApiKey: type: http scheme: bearer description: >- A workspace API key in an `Authorization: Bearer` header. A missing header, a scheme other than Bearer, a key of the wrong shape, and a key we reject are all 401. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.