{ "openapi": "3.1.0", "info": { "title": "Hedra API v3", "description": "Generate images, video, and audio with over 100 models through one API, including Veo 3.1, Seedance 2.0, Kling V3, GPT Image 2, Nano Banana Pro, and ElevenLabs V3. Create an API key and fund your wallet, then every model runs through the same three requests: submit a job, poll it, download the output. Input fields have the same names across models, such as `prompt`, `aspect_ratio`, `resolution`, `duration_ms`, and `start_image`, so switching models means changing the model id and choosing values the new model's schema accepts. Browse the [model catalog](https://www.hedra.com/develop/models) to pick one.\n\n**Authenticate** every request with your API key \u2014 create one in the [developer console](https://www.hedra.com/develop/api-keys): `Authorization: Key :`.\n\n**Fund the API wallet** before your first call. It is prepaid and held in US dollars, it is separate from your Hedra Studio balance, and a workspace starts with **$0.00** in it; nothing you buy or hold in Studio moves money into it. Until it is funded, every generation is refused with `402 INSUFFICIENT_BALANCE`; uploading inputs with `POST /files` is free and works on an empty wallet, so you can stage a request and only meet the gate at submit. Add funds in the [developer console](https://www.hedra.com/develop/billing), and read the wallet any time with `GET /balance`.\n\n**Quickstart** \u2014 submit a job, poll it, then read the output URL:\n\n```bash\n# 1. Submit \u2014 capture the job id from the 202 ack\nJOB_ID=$(curl -sS -X POST https://api.hedra.com/v3/models/gpt-image-2 \\\n -H \"Authorization: Key $HEDRA_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"input\": {\"prompt\": \"a space cat\", \"quality\": \"medium\", \"aspect_ratio\": \"1:1\", \"resolution\": \"1K\"}}' | jq -r .job_id)\n\n# 2. Poll until status is COMPLETED (or FAILED)\ncurl https://api.hedra.com/v3/jobs/$JOB_ID/status -H \"Authorization: Key $HEDRA_KEY\"\n\n# 3. Read the result \u2014 outputs[].url holds the generated file\ncurl https://api.hedra.com/v3/jobs/$JOB_ID -H \"Authorization: Key $HEDRA_KEY\"\n```\n\n**Follow a job without polling** \u2014 a video model can run for minutes, so the loop above suits fast image jobs and little else. Submit with a `webhook` URL and Hedra delivers the finished result there, ed25519-signed and retried; set `PUT /webhooks/default` once to cover every job that names no URL of its own, and see *Webhooks* for the signature scheme and the retry ladder. To watch one job live instead, open `GET /jobs/{job_id}/stream` \u2014 Server-Sent Events carrying every status transition and lifecycle event until the job reaches a terminal state.\n\n**Find a model** \u2014 `GET /models` lists every model with its `id` and human `name`; each operation in the *Run a model* section is titled with both, so a model you know by name (\"GPT Image 2\") maps straight to the id you submit to (`gpt-image-2`). One model's typed input schema: `GET /models/{id}/openapi.json`.\n\nEstimate cost before you run with `POST /models/{model}/estimate`. For volume pricing and custom limits, [talk to us](https://www.hedra.com/enterprise).\n\nThe full machine-readable spec is at `https://api.hedra.com/v3/openapi.json`.", "version": "3.17.8" }, "servers": [ { "url": "https://api.hedra.com/v3" } ], "paths": { "/jobs": { "get": { "tags": [ "Jobs" ], "summary": "List Jobs", "operationId": "jobs_list", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum items per page.", "default": 20, "title": "Limit" }, "description": "Maximum items per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor from the previous page's `next_cursor`; omit for the first page.", "title": "Cursor" }, "description": "Opaque cursor from the previous page's `next_cursor`; omit for the first page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobListResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/jobs\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.list()\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst pageableResponse = await client.jobs.list();\nfor await (const item of pageableResponse) {\n console.log(item);\n}\n\n// Or you can manually iterate page-by-page\nlet page = await client.jobs.list();\nwhile (page.hasNextPage()) {\n page = await page.getNextPage();\n}\n\n// You can also access the underlying response\nconst response = page.response;\n" } ] } }, "/jobs/{job_id}": { "get": { "tags": [ "Jobs" ], "summary": "Get Job", "operationId": "jobs_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The job's id (`job_`).", "title": "Job Id" }, "description": "The job's id (`job_`)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/jobs/{job_id}\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.get(\n job_id=\"job_id\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.get(\"job_id\");\n" } ] } }, "/jobs/{job_id}/status": { "get": { "tags": [ "Jobs" ], "summary": "Get Job Status", "operationId": "jobs_get_status", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The job's id (`job_`).", "title": "Job Id" }, "description": "The job's id (`job_`)." }, { "name": "logs_after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tail this job's lifecycle events incrementally: returns only events newer than this cursor, plus `logs_next_cursor` to send on the next poll. Pass `start` to begin from the job's first event. Omit it and the response carries no events at all \u2014 the default polling shape is unchanged.", "title": "Logs After" }, "description": "Tail this job's lifecycle events incrementally: returns only events newer than this cursor, plus `logs_next_cursor` to send on the next poll. Pass `start` to begin from the job's first event. Omit it and the response carries no events at all \u2014 the default polling shape is unchanged." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/jobs/{job_id}/status\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.get_status(\n job_id=\"job_id\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.getStatus(\"job_id\");\n" } ] } }, "/jobs/{job_id}/logs": { "get": { "tags": [ "Jobs" ], "summary": "List Job Logs", "operationId": "jobs_list_job_logs", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The job's id (`job_`).", "title": "Job Id" }, "description": "The job's id (`job_`)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum items per page.", "default": 20, "title": "Limit" }, "description": "Maximum items per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor from the previous page's `next_cursor`; omit for the first page.", "title": "Cursor" }, "description": "Opaque cursor from the previous page's `next_cursor`; omit for the first page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobLogListResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/jobs/{job_id}/logs\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.list_job_logs(\n job_id=\"job_id\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst pageableResponse = await client.jobs.listJobLogs(\"job_id\");\nfor await (const item of pageableResponse) {\n console.log(item);\n}\n\n// Or you can manually iterate page-by-page\nlet page = await client.jobs.listJobLogs(\"job_id\");\nwhile (page.hasNextPage()) {\n page = await page.getNextPage();\n}\n\n// You can also access the underlying response\nconst response = page.response;\n" } ] } }, "/jobs/{job_id}/stream": { "get": { "tags": [ "Jobs" ], "summary": "Stream Job", "operationId": "jobs_stream", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The job's id (`job_`).", "title": "Job Id" }, "description": "The job's id (`job_`)." }, { "name": "Last-Event-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resume after this event id \u2014 the standard SSE reconnect header; browsers' EventSource sends it automatically.", "title": "Last-Event-Id" }, "description": "Resume after this event id \u2014 the standard SSE reconnect header; browsers' EventSource sends it automatically." } ], "responses": { "200": { "description": "Server-Sent Events. Each frame's `event:` names its type. The `data:` line of a `status` frame is a `StatusResponse` and of a `log` frame a `JobLogItem` (the same row `GET /jobs/{job_id}/logs` serves), both JSON. The stream opens with a `status` snapshot and ends with a `done` frame, sent after the terminal `status` frame: reaching it means the job finished (`COMPLETED` or `FAILED`) and there is nothing more to read. A stream that ends without it was cut short; reconnect with `Last-Event-Id`. Closes the server initiates instead (drain, max connection duration) send a `retry:` line and no `done`. **The `done` frame's `data:` line is the literal token `[STREAM_DONE]` \u2014 not JSON, and not a member of the `JobStreamFrame` schema below.** It is a fixed end-of-stream sentinel, matched verbatim; switch on `event:` and skip `done` before parsing a `data:` line, or the parse fails on the last frame of every stream. It repeats no state: which job ended and how was just delivered by the terminal `status` frame. `status` and `log` frames carry an `id:` to send back as `Last-Event-Id`; `done` does not, since it is not a new stream position. Comment lines (`: keep-alive`) and `retry:` lines are protocol-level and carry no payload.", "content": { "text/event-stream": { "schema": { "title": "JobStreamFrame", "description": "The payload of one frame's `data:` line, selected by the frame's `event:` type \u2014 `status` carries a `StatusResponse`, `log` a `JobLogItem`. The terminating `done` frame is not covered here: its `data:` line is the literal token `[STREAM_DONE]`, not JSON.", "oneOf": [ { "$ref": "#/components/schemas/StatusResponse" }, { "$ref": "#/components/schemas/JobLogItem" } ] } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/jobs/{job_id}/stream\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.stream(\n job_id=\"job_id\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await client.jobs.stream(\"job_id\");\nfor await (const item of response) {\n console.log(item);\n}\n" } ] } }, "/models": { "get": { "tags": [ "Models" ], "summary": "List Models", "operationId": "models_list", "parameters": [ { "name": "modality", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/Modality" }, { "type": "null" } ], "description": "Only models with this modality, matching `modality` on each returned model.", "title": "Modality" }, "description": "Only models with this modality, matching `modality` on each returned model." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelListResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/models\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.models.list()\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.models.list();\n" } ] } }, "/models/creatify-aurora": { "post": { "tags": [ "Run a model" ], "operationId": "submit_creatify_aurora", "summary": "Run Creatify Aurora (creatify-aurora)", "description": "Create high-fidelity speaking or singing avatar videos.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_creatify_aurora" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/creatify-aurora\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"audio\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n },\n \"resolution\": \"480p\",\n \"start_image\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputCreatifyAurora, InputCreatifyAuroraStartImage_Url, InputCreatifyAuroraAudio_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_creatify_aurora(\n input=InputCreatifyAurora(\n resolution=\"480p\",\n start_image=InputCreatifyAuroraStartImage_Url(\n url=\"url\",\n ),\n audio=InputCreatifyAuroraAudio_Url(\n url=\"url\",\n ),\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitCreatifyAurora({\n input: {\n resolution: \"480p\",\n start_image: {\n source: \"url\",\n url: \"url\"\n },\n audio: {\n source: \"url\",\n url: \"url\"\n }\n }\n});\n" } ] } }, "/models/dreamina-31": { "post": { "tags": [ "Run a model" ], "operationId": "submit_dreamina_31", "summary": "Run Dreamina 3.1 (dreamina-31)", "description": "Polished, print-ready stills when the brief is a finished image rather than a sketch.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_dreamina_31" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/dreamina-31\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\",\n \"resolution\": \"540p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputDreamina31\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_dreamina31(\n input=InputDreamina31(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n resolution=\"540p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitDreamina31({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n resolution: \"540p\"\n }\n});\n" } ] } }, "/models/elevenlabs-audio-isolation": { "post": { "tags": [ "Run a model" ], "operationId": "submit_elevenlabs_audio_isolation", "summary": "Run ElevenLabs Audio Isolation (elevenlabs-audio-isolation)", "description": "Strip background noise from a recording, keeping the speech.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_elevenlabs_audio_isolation" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/elevenlabs-audio-isolation\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"audio\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputElevenlabsAudioIsolation, InputElevenlabsAudioIsolationAudio_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_elevenlabs_audio_isolation(\n input=InputElevenlabsAudioIsolation(\n audio=InputElevenlabsAudioIsolationAudio_Url(\n url=\"url\",\n ),\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitElevenlabsAudioIsolation({\n input: {\n audio: {\n source: \"url\",\n url: \"url\"\n }\n }\n});\n" } ] } }, "/models/elevenlabs-english-sts-v2": { "post": { "tags": [ "Run a model" ], "operationId": "submit_elevenlabs_english_sts_v2", "summary": "Run ElevenLabs English STS V2 (elevenlabs-english-sts-v2)", "description": "Submits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_elevenlabs_english_sts_v2" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/elevenlabs-english-sts-v2\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"audio\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n },\n \"voice_id\": \"voice_id\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputElevenlabsEnglishStsV2, InputElevenlabsEnglishStsV2Audio_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_elevenlabs_english_sts_v2(\n input=InputElevenlabsEnglishStsV2(\n audio=InputElevenlabsEnglishStsV2Audio_Url(\n url=\"url\",\n ),\n voice_id=\"voice_id\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitElevenlabsEnglishStsV2({\n input: {\n audio: {\n source: \"url\",\n url: \"url\"\n },\n voice_id: \"voice_id\"\n }\n});\n" } ] } }, "/models/elevenlabs-flash-multilingual-v2": { "post": { "tags": [ "Run a model" ], "operationId": "submit_elevenlabs_flash_multilingual_v2", "summary": "Run ElevenLabs Flash Multilingual V2 (elevenlabs-flash-multilingual-v2)", "description": "The low-latency voice across 30+ languages, for interactive and high-volume speech.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_elevenlabs_flash_multilingual_v2" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/elevenlabs-flash-multilingual-v2\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"text\": \"text\",\n \"voice_id\": \"voice_id\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputElevenlabsFlashMultilingualV2\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_elevenlabs_flash_multilingual_v2(\n input=InputElevenlabsFlashMultilingualV2(\n text=\"text\",\n voice_id=\"voice_id\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitElevenlabsFlashMultilingualV2({\n input: {\n text: \"text\",\n voice_id: \"voice_id\"\n }\n});\n" } ] } }, "/models/elevenlabs-flash-v2": { "post": { "tags": [ "Run a model" ], "operationId": "submit_elevenlabs_flash_v2", "summary": "Run ElevenLabs Flash V2 (elevenlabs-flash-v2)", "description": "The low-latency English voice, for interactive speech.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_elevenlabs_flash_v2" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/elevenlabs-flash-v2\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"text\": \"text\",\n \"voice_id\": \"voice_id\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputElevenlabsFlashV2\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_elevenlabs_flash_v2(\n input=InputElevenlabsFlashV2(\n text=\"text\",\n voice_id=\"voice_id\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitElevenlabsFlashV2({\n input: {\n text: \"text\",\n voice_id: \"voice_id\"\n }\n});\n" } ] } }, "/models/elevenlabs-multilingual-sts-v2": { "post": { "tags": [ "Run a model" ], "operationId": "submit_elevenlabs_multilingual_sts_v2", "summary": "Run ElevenLabs Multilingual STS V2 (elevenlabs-multilingual-sts-v2)", "description": "Submits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_elevenlabs_multilingual_sts_v2" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/elevenlabs-multilingual-sts-v2\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"audio\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n },\n \"voice_id\": \"voice_id\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputElevenlabsMultilingualStsV2, InputElevenlabsMultilingualStsV2Audio_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_elevenlabs_multilingual_sts_v2(\n input=InputElevenlabsMultilingualStsV2(\n audio=InputElevenlabsMultilingualStsV2Audio_Url(\n url=\"url\",\n ),\n voice_id=\"voice_id\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitElevenlabsMultilingualStsV2({\n input: {\n audio: {\n source: \"url\",\n url: \"url\"\n },\n voice_id: \"voice_id\"\n }\n});\n" } ] } }, "/models/elevenlabs-multilingual-v2": { "post": { "tags": [ "Run a model" ], "operationId": "submit_elevenlabs_multilingual_v2", "summary": "Run ElevenLabs Multilingual V2 (elevenlabs-multilingual-v2)", "description": "Steady, natural narration across 30+ languages, for finished voiceover.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_elevenlabs_multilingual_v2" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/elevenlabs-multilingual-v2\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"text\": \"text\",\n \"voice_id\": \"voice_id\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputElevenlabsMultilingualV2\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_elevenlabs_multilingual_v2(\n input=InputElevenlabsMultilingualV2(\n text=\"text\",\n voice_id=\"voice_id\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitElevenlabsMultilingualV2({\n input: {\n text: \"text\",\n voice_id: \"voice_id\"\n }\n});\n" } ] } }, "/models/elevenlabs-music": { "post": { "tags": [ "Run a model" ], "operationId": "submit_elevenlabs_music", "summary": "Run ElevenLabs Music (elevenlabs-music)", "description": "Full tracks from a written brief, with optional lyrics placed across the length you ask for.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_elevenlabs_music" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/elevenlabs-music\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"duration_ms\": 3000,\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputElevenlabsMusic\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_elevenlabs_music(\n input=InputElevenlabsMusic(\n prompt=\"prompt\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitElevenlabsMusic({\n input: {\n prompt: \"prompt\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/elevenlabs-sound-effects": { "post": { "tags": [ "Run a model" ], "operationId": "submit_elevenlabs_sound_effects", "summary": "Run ElevenLabs Sound Effects (elevenlabs-sound-effects)", "description": "One-off sound effects from a written description, loopable on request.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_elevenlabs_sound_effects" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/elevenlabs-sound-effects\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"duration_ms\": 500,\n \"text\": \"text\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputElevenlabsSoundEffects\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_elevenlabs_sound_effects(\n input=InputElevenlabsSoundEffects(\n text=\"text\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitElevenlabsSoundEffects({\n input: {\n text: \"text\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/elevenlabs-v3": { "post": { "tags": [ "Run a model" ], "operationId": "submit_elevenlabs_v3", "summary": "Run ElevenLabs V3 (elevenlabs-v3)", "description": "The most expressive ElevenLabs voice \u2014 emotional range and delivery cues for performance, not just narration.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_elevenlabs_v3" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/elevenlabs-v3\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"text\": \"text\",\n \"voice_id\": \"voice_id\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputElevenlabsV3\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_elevenlabs_v3(\n input=InputElevenlabsV3(\n text=\"text\",\n voice_id=\"voice_id\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitElevenlabsV3({\n input: {\n text: \"text\",\n voice_id: \"voice_id\"\n }\n});\n" } ] } }, "/models/elevenlabs-voice-clone": { "post": { "tags": [ "Run a model" ], "operationId": "submit_elevenlabs_voice_clone", "summary": "Run ElevenLabs Voice Clone (elevenlabs-voice-clone)", "description": "Use an audio clip to create a new Voice.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_elevenlabs_voice_clone" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/elevenlabs-voice-clone\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"audio\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n },\n \"name\": \"name\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputElevenlabsVoiceClone, InputElevenlabsVoiceCloneAudio_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_elevenlabs_voice_clone(\n input=InputElevenlabsVoiceClone(\n audio=InputElevenlabsVoiceCloneAudio_Url(\n url=\"url\",\n ),\n name=\"name\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitElevenlabsVoiceClone({\n input: {\n audio: {\n source: \"url\",\n url: \"url\"\n },\n name: \"name\"\n }\n});\n" } ] } }, "/models/eyeline-id-relight": { "post": { "tags": [ "Run a model" ], "operationId": "submit_eyeline_id_relight", "summary": "Run Eyeline ID Relight (eyeline-id-relight)", "description": "Relight a video from a relit first frame, keeping the scene, the subjects and the original performance.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_eyeline_id_relight" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/eyeline-id-relight\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"images\": [\n {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n ],\n \"prompt\": \"prompt\",\n \"source_video\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputEyelineIdRelight, InputEyelineIdRelightSourceVideo_Url, InputEyelineIdRelightImagesItem_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_eyeline_id_relight(\n input=InputEyelineIdRelight(\n prompt=\"prompt\",\n source_video=InputEyelineIdRelightSourceVideo_Url(\n url=\"url\",\n ),\n images=[\n InputEyelineIdRelightImagesItem_Url(\n url=\"url\",\n )\n ],\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitEyelineIdRelight({\n input: {\n prompt: \"prompt\",\n source_video: {\n source: \"url\",\n url: \"url\"\n },\n images: [{\n source: \"url\",\n url: \"url\"\n }]\n }\n});\n" } ] } }, "/models/eyeline-id-restyle": { "post": { "tags": [ "Run a model" ], "operationId": "submit_eyeline_id_restyle", "summary": "Run Eyeline ID Restyle (eyeline-id-restyle)", "description": "Restyle a video's scene, lighting and look from an edited first frame while keeping the people in it recognizably themselves.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_eyeline_id_restyle" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/eyeline-id-restyle\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"images\": [\n {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n ],\n \"prompt\": \"prompt\",\n \"source_video\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputEyelineIdRestyle, InputEyelineIdRestyleSourceVideo_Url, InputEyelineIdRestyleImagesItem_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_eyeline_id_restyle(\n input=InputEyelineIdRestyle(\n prompt=\"prompt\",\n source_video=InputEyelineIdRestyleSourceVideo_Url(\n url=\"url\",\n ),\n images=[\n InputEyelineIdRestyleImagesItem_Url(\n url=\"url\",\n )\n ],\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitEyelineIdRestyle({\n input: {\n prompt: \"prompt\",\n source_video: {\n source: \"url\",\n url: \"url\"\n },\n images: [{\n source: \"url\",\n url: \"url\"\n }]\n }\n});\n" } ] } }, "/models/flux-11-pro": { "post": { "tags": [ "Run a model" ], "operationId": "submit_flux_11_pro", "summary": "Run Flux 1.1 Pro (flux-11-pro)", "description": "Premium color depth and clarity when you want campaign-ready art that feels handcrafted.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_flux_11_pro" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/flux-11-pro\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"prompt\": \"prompt\",\n \"resolution\": \"540p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputFlux11Pro\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_flux11pro(\n input=InputFlux11Pro(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n resolution=\"540p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitFlux11Pro({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\",\n resolution: \"540p\"\n }\n});\n" } ] } }, "/models/flux-11-ultra": { "post": { "tags": [ "Run a model" ], "operationId": "submit_flux_11_ultra", "summary": "Run Flux 1.1 Ultra (flux-11-ultra)", "description": "The big-canvas choice for ultra-high-res images and flagship visuals.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_flux_11_ultra" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/flux-11-ultra\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputFlux11Ultra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_flux11ultra(\n input=InputFlux11Ultra(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitFlux11Ultra({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\"\n }\n});\n" } ] } }, "/models/flux-3": { "post": { "tags": [ "Run a model" ], "operationId": "submit_flux_3", "summary": "Run FLUX.3 (flux-3)", "description": "Video with native audio, straight from a prompt.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_flux_3" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/flux-3\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"auto\",\n \"duration_ms\": 5000,\n \"prompt\": \"prompt\",\n \"resolution\": \"720p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputFlux3\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_flux3(\n input=InputFlux3(\n prompt=\"prompt\",\n aspect_ratio=\"auto\",\n resolution=\"720p\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitFlux3({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"auto\",\n resolution: \"720p\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/flux-3-video-upscaler-creative": { "post": { "tags": [ "Run a model" ], "operationId": "submit_flux_3_video_upscaler_creative", "summary": "Run FLUX.3 Video Upscaler Creative (flux-3-video-upscaler-creative)", "description": "Super-resolution that adds detail as it enlarges, for soft or low-resolution footage.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_flux_3_video_upscaler_creative" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/flux-3-video-upscaler-creative\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"resolution\": \"1080p\",\n \"source_video\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputFlux3VideoUpscalerCreative, InputFlux3VideoUpscalerCreativeSourceVideo_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_flux3video_upscaler_creative(\n input=InputFlux3VideoUpscalerCreative(\n source_video=InputFlux3VideoUpscalerCreativeSourceVideo_Url(\n url=\"url\",\n ),\n resolution=\"1080p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitFlux3VideoUpscalerCreative({\n input: {\n source_video: {\n source: \"url\",\n url: \"url\"\n },\n resolution: \"1080p\"\n }\n});\n" } ] } }, "/models/flux-3-video-upscaler-precise": { "post": { "tags": [ "Run a model" ], "operationId": "submit_flux_3_video_upscaler_precise", "summary": "Run FLUX.3 Video Upscaler Precise (flux-3-video-upscaler-precise)", "description": "Super-resolution that reproduces the source faithfully, for footage whose detail should not change.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_flux_3_video_upscaler_precise" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/flux-3-video-upscaler-precise\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"resolution\": \"1080p\",\n \"source_video\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputFlux3VideoUpscalerPrecise, InputFlux3VideoUpscalerPreciseSourceVideo_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_flux3video_upscaler_precise(\n input=InputFlux3VideoUpscalerPrecise(\n source_video=InputFlux3VideoUpscalerPreciseSourceVideo_Url(\n url=\"url\",\n ),\n resolution=\"1080p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitFlux3VideoUpscalerPrecise({\n input: {\n source_video: {\n source: \"url\",\n url: \"url\"\n },\n resolution: \"1080p\"\n }\n});\n" } ] } }, "/models/flux-dev": { "post": { "tags": [ "Run a model" ], "operationId": "submit_flux_dev", "summary": "Run Flux Dev (flux-dev)", "description": "Fast and light for quick concepts or high-volume social posts on a budget.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_flux_dev" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/flux-dev\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"prompt\": \"prompt\",\n \"resolution\": \"540p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputFluxDev\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_flux_dev(\n input=InputFluxDev(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n resolution=\"540p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitFluxDev({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\",\n resolution: \"540p\"\n }\n});\n" } ] } }, "/models/flux-kontext-max": { "post": { "tags": [ "Run a model" ], "operationId": "submit_flux_kontext_max", "summary": "Run Flux Kontext Max (flux-kontext-max)", "description": "Highest-fidelity reference-image support for complex, multi-element scenes and perfectly matched branded visuals.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_flux_kontext_max" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/flux-kontext-max\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputFluxKontextMax\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_flux_kontext_max(\n input=InputFluxKontextMax(\n prompt=\"prompt\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitFluxKontextMax({\n input: {\n prompt: \"prompt\"\n }\n});\n" } ] } }, "/models/flux-kontext-pro": { "post": { "tags": [ "Run a model" ], "operationId": "submit_flux_kontext_pro", "summary": "Run Flux Kontext Pro (flux-kontext-pro)", "description": "Reference-image support for character, brand, or style consistency.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_flux_kontext_pro" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/flux-kontext-pro\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputFluxKontextPro\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_flux_kontext_pro(\n input=InputFluxKontextPro(\n prompt=\"prompt\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitFluxKontextPro({\n input: {\n prompt: \"prompt\"\n }\n});\n" } ] } }, "/models/flux2-flex": { "post": { "tags": [ "Run a model" ], "operationId": "submit_flux2_flex", "summary": "Run Flux.2 [flex] (flux2-flex)", "description": "The tunable Flux.2 tier \u2014 trade denoising steps against speed per generation.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_flux2_flex" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/flux2-flex\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputFlux2Flex\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_flux2flex(\n input=InputFlux2Flex(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitFlux2Flex({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\"\n }\n});\n" } ] } }, "/models/flux2-klein-9b": { "post": { "tags": [ "Run a model" ], "operationId": "submit_flux2_klein_9b", "summary": "Run Flux.2 [klein] 9B (flux2-klein-9b)", "description": "The lean Flux.2 tier \u2014 quick, inexpensive stills for concepting and high-volume work.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_flux2_klein_9b" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/flux2-klein-9b\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputFlux2Klein9B\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_flux2klein9b(\n input=InputFlux2Klein9B(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitFlux2Klein9B({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\"\n }\n});\n" } ] } }, "/models/flux2-max": { "post": { "tags": [ "Run a model" ], "operationId": "submit_flux2_max", "summary": "Run Flux.2 [max] (flux2-max)", "description": "The top Flux.2 tier, for realism and precision in final deliverables.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_flux2_max" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/flux2-max\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputFlux2Max\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_flux2max(\n input=InputFlux2Max(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitFlux2Max({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\"\n }\n});\n" } ] } }, "/models/flux2-pro": { "post": { "tags": [ "Run a model" ], "operationId": "submit_flux2_pro", "summary": "Run Flux.2 [pro] (flux2-pro)", "description": "The everyday Flux.2 tier \u2014 style transfer and sequential edits that hold together across passes.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_flux2_pro" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/flux2-pro\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputFlux2Pro\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_flux2pro(\n input=InputFlux2Pro(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitFlux2Pro({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\"\n }\n});\n" } ] } }, "/models/gemini-omni-flash": { "post": { "tags": [ "Run a model" ], "operationId": "submit_gemini_omni_flash", "summary": "Run Gemini Omni Flash (gemini-omni-flash)", "description": "Gemini's fast multimodal video model \u2014 cinematic clips with native audio from a prompt, a keyframe, or reference images.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_gemini_omni_flash" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/gemini-omni-flash\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputGeminiOmniFlash\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_gemini_omni_flash(\n input=InputGeminiOmniFlash(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitGeminiOmniFlash({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\"\n }\n});\n" } ] } }, "/models/gemini-omni-flash-11": { "post": { "tags": [ "Run a model" ], "operationId": "submit_gemini_omni_flash_11", "summary": "Run Gemini Omni 1.1 Flash (gemini-omni-flash-11)", "description": "Gemini's fast multimodal video model \u2014 cinematic clips with native audio, from a prompt, a keyframe pair, or reference images, up to 4K.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_gemini_omni_flash_11" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/gemini-omni-flash-11\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\",\n \"resolution\": \"360p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputGeminiOmniFlash11\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_gemini_omni_flash11(\n input=InputGeminiOmniFlash11(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n resolution=\"360p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitGeminiOmniFlash11({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n resolution: \"360p\"\n }\n});\n" } ] } }, "/models/gpt-image-15": { "post": { "tags": [ "Run a model" ], "operationId": "submit_gpt_image_15", "summary": "Run GPT Image 1.5 (gpt-image-15)", "description": "Reads a long, specific brief closely \u2014 the choice when the prompt carries the detail.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_gpt_image_15" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/gpt-image-15\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputGptImage15\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_gpt_image15(\n input=InputGptImage15(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitGptImage15({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\"\n }\n});\n" } ] } }, "/models/gpt-image-2": { "post": { "tags": [ "Run a model" ], "operationId": "submit_gpt_image_2", "summary": "Run GPT Image 2 (gpt-image-2)", "description": "OpenAI's balanced tier; moderate cost and fidelity, ideal for iterative refinement and everyday generation.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_gpt_image_2" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/gpt-image-2\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\",\n \"resolution\": \"1K\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputGptImage2\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_gpt_image2(\n input=InputGptImage2(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n resolution=\"1K\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitGptImage2({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n resolution: \"1K\"\n }\n});\n" } ] } }, "/models/gpt-image-2.5-flare": { "post": { "tags": [ "Run a model" ], "operationId": "submit_gpt_image_2.5_flare", "summary": "Run GPT Image 2.5 Flare (gpt-image-2.5-flare)", "description": "OpenAI's GPT Image 2.5 Flare; automatically selects rendering quality for the prompt.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_gpt_image_2.5_flare" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/gpt-image-2.5-flare\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\",\n \"resolution\": \"1K\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputGptImage25Flare\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_gpt_image25flare(\n input=InputGptImage25Flare(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n resolution=\"1K\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitGptImage25Flare({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n resolution: \"1K\"\n }\n});\n" } ] } }, "/models/gpt-image-2.5-sunburst": { "post": { "tags": [ "Run a model" ], "operationId": "submit_gpt_image_2.5_sunburst", "summary": "Run GPT Image 2.5 Sunburst (gpt-image-2.5-sunburst)", "description": "OpenAI's GPT Image 2.5 Sunburst; automatically selects rendering quality for the prompt.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_gpt_image_2.5_sunburst" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/gpt-image-2.5-sunburst\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\",\n \"resolution\": \"1K\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputGptImage25Sunburst\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_gpt_image25sunburst(\n input=InputGptImage25Sunburst(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n resolution=\"1K\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitGptImage25Sunburst({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n resolution: \"1K\"\n }\n});\n" } ] } }, "/models/grok-imagine": { "post": { "tags": [ "Run a model" ], "operationId": "submit_grok_imagine", "summary": "Run Grok Imagine (grok-imagine)", "description": "Grok's take on a prompt \u2014 punchy, irreverent stills, in everything from ultrawide to tall.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_grok_imagine" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/grok-imagine\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputGrokImagine\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_grok_imagine(\n input=InputGrokImagine(\n prompt=\"prompt\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitGrokImagine({\n input: {\n prompt: \"prompt\"\n }\n});\n" } ] } }, "/models/grok-imagine-20": { "post": { "tags": [ "Run a model" ], "operationId": "submit_grok_imagine_20", "summary": "Run Grok Imagine 2.0 (grok-imagine-20)", "description": "xAI's current Grok Imagine \u2014 the same irreverence at higher fidelity, from a prompt or from up to three source images.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_grok_imagine_20" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/grok-imagine-20\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"2:1\",\n \"prompt\": \"prompt\",\n \"resolution\": \"1k\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputGrokImagine20\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_grok_imagine20(\n input=InputGrokImagine20(\n prompt=\"prompt\",\n aspect_ratio=\"2:1\",\n resolution=\"1k\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitGrokImagine20({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"2:1\",\n resolution: \"1k\"\n }\n});\n" } ] } }, "/models/grok-video": { "post": { "tags": [ "Run a model" ], "operationId": "submit_grok_video", "summary": "Run Grok Video (grok-video)", "description": "Short, punchy clips from a prompt at 480p or 720p.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_grok_video" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/grok-video\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"auto\",\n \"duration_ms\": 1000,\n \"prompt\": \"prompt\",\n \"resolution\": \"480p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputGrokVideo\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_grok_video(\n input=InputGrokVideo(\n prompt=\"prompt\",\n aspect_ratio=\"auto\",\n resolution=\"480p\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitGrokVideo({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"auto\",\n resolution: \"480p\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/happy-horse": { "post": { "tags": [ "Run a model" ], "operationId": "submit_happy_horse", "summary": "Run Happy Horse (happy-horse)", "description": "Open-weight video from a prompt, from a first frame, or from up to nine reference images you direct by name as character1..character9.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_happy_horse" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/happy-horse\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"duration_ms\": 3000,\n \"prompt\": \"prompt\",\n \"resolution\": \"720p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputHappyHorse\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_happy_horse(\n input=InputHappyHorse(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n resolution=\"720p\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitHappyHorse({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n resolution: \"720p\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/hedra-avatar": { "post": { "tags": [ "Run a model" ], "operationId": "submit_hedra_avatar", "summary": "Run Hedra Avatar (hedra-avatar)", "description": "Hedra's latest longform avatar model, audio to video will full multi-language support. Perfect for talking and singing video with speaker selection up to 10 minutes long.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_hedra_avatar" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/hedra-avatar\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"audio\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n },\n \"prompt\": \"prompt\",\n \"resolution\": \"540p\",\n \"start_image\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputHedraAvatar, InputHedraAvatarStartImage_Url, InputHedraAvatarAudioZero_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_hedra_avatar(\n input=InputHedraAvatar(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n resolution=\"540p\",\n start_image=InputHedraAvatarStartImage_Url(\n url=\"url\",\n ),\n audio=InputHedraAvatarAudioZero_Url(\n url=\"url\",\n ),\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitHedraAvatar({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\",\n resolution: \"540p\",\n start_image: {\n source: \"url\",\n url: \"url\"\n },\n audio: {\n source: \"url\",\n url: \"url\"\n }\n }\n});\n" } ] } }, "/models/hedra-character-3": { "post": { "tags": [ "Run a model" ], "operationId": "submit_hedra_character_3", "summary": "Run Hedra Character 3 (hedra-character-3)", "description": "Hedra's latest longform avatar model, audio to video will full multi-language support. Perfect for talking and singing video with speaker selection up to 10 minutes long.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_hedra_character_3" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/hedra-character-3\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"audio\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n },\n \"prompt\": \"prompt\",\n \"resolution\": \"540p\",\n \"start_image\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputHedraCharacter3, InputHedraCharacter3StartImage_Url, InputHedraCharacter3AudioZero_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_hedra_character3(\n input=InputHedraCharacter3(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n resolution=\"540p\",\n start_image=InputHedraCharacter3StartImage_Url(\n url=\"url\",\n ),\n audio=InputHedraCharacter3AudioZero_Url(\n url=\"url\",\n ),\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitHedraCharacter3({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\",\n resolution: \"540p\",\n start_image: {\n source: \"url\",\n url: \"url\"\n },\n audio: {\n source: \"url\",\n url: \"url\"\n }\n }\n});\n" } ] } }, "/models/heygen-photo-avatar-4": { "post": { "tags": [ "Run a model" ], "operationId": "submit_heygen_photo_avatar_4", "summary": "Run HeyGen Photo Avatar 4 (heygen-photo-avatar-4)", "description": "Turn a clear portrait and driving audio into a talking avatar.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_heygen_photo_avatar_4" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/heygen-photo-avatar-4\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"audio\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n },\n \"resolution\": \"360p\",\n \"start_image\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputHeygenPhotoAvatar4, InputHeygenPhotoAvatar4StartImage_Url, InputHeygenPhotoAvatar4Audio_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_heygen_photo_avatar4(\n input=InputHeygenPhotoAvatar4(\n aspect_ratio=\"16:9\",\n resolution=\"360p\",\n start_image=InputHeygenPhotoAvatar4StartImage_Url(\n url=\"url\",\n ),\n audio=InputHeygenPhotoAvatar4Audio_Url(\n url=\"url\",\n ),\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitHeygenPhotoAvatar4({\n input: {\n aspect_ratio: \"16:9\",\n resolution: \"360p\",\n start_image: {\n source: \"url\",\n url: \"url\"\n },\n audio: {\n source: \"url\",\n url: \"url\"\n }\n }\n});\n" } ] } }, "/models/hidream-o1-image": { "post": { "tags": [ "Run a model" ], "operationId": "submit_hidream_o1_image", "summary": "Run HiDream-O1-Image (hidream-o1-image)", "description": "HiDream.ai's open-weights HiDream-O1-Image (8B): one pixel-native model that generates, edits, and personalizes without a VAE or a separate text encoder.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_hidream_o1_image" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/hidream-o1-image\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputHidreamO1Image\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_hidream_o1image(\n input=InputHidreamO1Image(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitHidreamO1Image({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\"\n }\n});\n" } ] } }, "/models/ideogram-v2": { "post": { "tags": [ "Run a model" ], "operationId": "submit_ideogram_v2", "summary": "Run Ideogram V2 (ideogram-v2)", "description": "Best in class for poster-ready images and spot-on text rendering in social graphics.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_ideogram_v2" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/ideogram-v2\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputIdeogramV2\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_ideogram_v2(\n input=InputIdeogramV2(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitIdeogramV2({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\"\n }\n});\n" } ] } }, "/models/ideogram-v4": { "post": { "tags": [ "Run a model" ], "operationId": "submit_ideogram_v4", "summary": "Run Ideogram V4 (ideogram-v4)", "description": "Ideogram V4 renders poster-ready text and layout; the required quality parameter picks turbo, balanced or quality, which sets both the render effort and the price.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_ideogram_v4" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/ideogram-v4\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\",\n \"resolution\": \"720p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputIdeogramV4\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_ideogram_v4(\n input=InputIdeogramV4(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n resolution=\"720p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitIdeogramV4({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n resolution: \"720p\"\n }\n});\n" } ] } }, "/models/imagen3": { "post": { "tags": [ "Run a model" ], "operationId": "submit_imagen3", "summary": "Run Imagen3 (imagen3)", "description": "Google's earlier photoreal generator, kept for parity.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_imagen3" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/imagen3\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputImagen3\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_imagen3(\n input=InputImagen3(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitImagen3({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\"\n }\n});\n" } ] } }, "/models/imagen4": { "post": { "tags": [ "Run a model" ], "operationId": "submit_imagen4", "summary": "Run Imagen4 (imagen4)", "description": "Google's photoreal model\u2014natural lighting, lifelike skin, and pro-grade sharpness in every shot.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_imagen4" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/imagen4\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\",\n \"resolution\": \"1K\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputImagen4\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_imagen4(\n input=InputImagen4(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n resolution=\"1K\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitImagen4({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n resolution: \"1K\"\n }\n});\n" } ] } }, "/models/kling-16": { "post": { "tags": [ "Run a model" ], "operationId": "submit_kling_16", "summary": "Run Kling 1.6 (kling-16)", "description": "Submits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_kling_16" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/kling-16\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputKling16\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_kling16(\n input=InputKling16(\n prompt=\"prompt\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitKling16({\n input: {\n prompt: \"prompt\"\n }\n});\n" } ] } }, "/models/kling-21-master": { "post": { "tags": [ "Run a model" ], "operationId": "submit_kling_21_master", "summary": "Run Kling 2.1 Master (kling-21-master)", "description": "Cinema-grade video with striking textures and rich depth.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_kling_21_master" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/kling-21-master\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"duration_ms\": 5000,\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputKling21Master\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_kling21master(\n input=InputKling21Master(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitKling21Master({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/kling-25-turbo": { "post": { "tags": [ "Run a model" ], "operationId": "submit_kling_25_turbo", "summary": "Run Kling 2.5 Turbo (kling-25-turbo)", "description": "Fast, high-quality video generation.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_kling_25_turbo" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/kling-25-turbo\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"duration_ms\": 5000,\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputKling25Turbo\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_kling25turbo(\n input=InputKling25Turbo(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitKling25Turbo({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/kling-26-motion-control": { "post": { "tags": [ "Run a model" ], "operationId": "submit_kling_26_motion_control", "summary": "Run Kling 2.6 Motion Control (kling-26-motion-control)", "description": "Transfer movements from a reference video to any character image. Cost-effective mode for motion transfer, perfect for portraits and simple animations.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_kling_26_motion_control" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/kling-26-motion-control\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"resolution\": \"720p\",\n \"source_video\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n },\n \"start_image\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputKling26MotionControl, InputKling26MotionControlStartImage_Url, InputKling26MotionControlSourceVideo_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_kling26motion_control(\n input=InputKling26MotionControl(\n start_image=InputKling26MotionControlStartImage_Url(\n url=\"url\",\n ),\n source_video=InputKling26MotionControlSourceVideo_Url(\n url=\"url\",\n ),\n resolution=\"720p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitKling26MotionControl({\n input: {\n start_image: {\n source: \"url\",\n url: \"url\"\n },\n source_video: {\n source: \"url\",\n url: \"url\"\n },\n resolution: \"720p\"\n }\n});\n" } ] } }, "/models/kling-26-pro": { "post": { "tags": [ "Run a model" ], "operationId": "submit_kling_26_pro", "summary": "Run Kling 2.6 Pro (kling-26-pro)", "description": "Cinematic visuals, fluid motion, and native audio generation.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_kling_26_pro" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/kling-26-pro\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"duration_ms\": 5000,\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputKling26Pro\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_kling26pro(\n input=InputKling26Pro(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitKling26Pro({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/kling-ai-avatar-v2": { "post": { "tags": [ "Run a model" ], "operationId": "submit_kling_ai_avatar_v2", "summary": "Run Kling AI Avatar v2 (kling-ai-avatar-v2)", "description": "Create avatar videos with realistic humans, animals, cartoons, or stylized characters from an image and audio input.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_kling_ai_avatar_v2" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/kling-ai-avatar-v2\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"audio\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n },\n \"start_image\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputKlingAiAvatarV2, InputKlingAiAvatarV2StartImage_Url, InputKlingAiAvatarV2Audio_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_kling_ai_avatar_v2(\n input=InputKlingAiAvatarV2(\n aspect_ratio=\"16:9\",\n start_image=InputKlingAiAvatarV2StartImage_Url(\n url=\"url\",\n ),\n audio=InputKlingAiAvatarV2Audio_Url(\n url=\"url\",\n ),\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitKlingAiAvatarV2({\n input: {\n aspect_ratio: \"16:9\",\n start_image: {\n source: \"url\",\n url: \"url\"\n },\n audio: {\n source: \"url\",\n url: \"url\"\n }\n }\n});\n" } ] } }, "/models/kling-o1": { "post": { "tags": [ "Run a model" ], "operationId": "submit_kling_o1", "summary": "Run Kling O1 (kling-o1)", "description": "Generate from a single image with text-driven style and scene guidance.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_kling_o1" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/kling-o1\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"duration_ms\": 3000,\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputKlingO1\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_kling_o1(\n input=InputKlingO1(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitKlingO1({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/kling-o3": { "post": { "tags": [ "Run a model" ], "operationId": "submit_kling_o3", "summary": "Run Kling O3 (kling-o3)", "description": "Clips up to 15 seconds with native audio.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_kling_o3" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/kling-o3\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"resolution\": \"1080p\",\n \"aspect_ratio\": \"16:9\",\n \"duration_ms\": 3000\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputKlingO3\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_kling_o3(\n input=InputKlingO3(\n aspect_ratio=\"16:9\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitKlingO3({\n input: {\n aspect_ratio: \"16:9\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/kling-o3-edit": { "post": { "tags": [ "Run a model" ], "operationId": "submit_kling_o3_edit", "summary": "Run Kling O3 Edit (kling-o3-edit)", "description": "Edit videos using natural language.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_kling_o3_edit" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/kling-o3-edit\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"prompt\": \"prompt\",\n \"resolution\": \"720p\",\n \"source_video\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputKlingO3Edit, InputKlingO3EditSourceVideo_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_kling_o3edit(\n input=InputKlingO3Edit(\n prompt=\"prompt\",\n source_video=InputKlingO3EditSourceVideo_Url(\n url=\"url\",\n ),\n resolution=\"720p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitKlingO3Edit({\n input: {\n prompt: \"prompt\",\n source_video: {\n source: \"url\",\n url: \"url\"\n },\n resolution: \"720p\"\n }\n});\n" } ] } }, "/models/kling-o3-reference": { "post": { "tags": [ "Run a model" ], "operationId": "submit_kling_o3_reference", "summary": "Run Kling O3 Reference (kling-o3-reference)", "description": "Input a reference video and preserve motion and camera style.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_kling_o3_reference" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/kling-o3-reference\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"prompt\": \"prompt\",\n \"resolution\": \"720p\",\n \"source_video\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputKlingO3Reference, InputKlingO3ReferenceSourceVideo_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_kling_o3reference(\n input=InputKlingO3Reference(\n prompt=\"prompt\",\n source_video=InputKlingO3ReferenceSourceVideo_Url(\n url=\"url\",\n ),\n resolution=\"720p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitKlingO3Reference({\n input: {\n prompt: \"prompt\",\n source_video: {\n source: \"url\",\n url: \"url\"\n },\n resolution: \"720p\"\n }\n});\n" } ] } }, "/models/kling-v3": { "post": { "tags": [ "Run a model" ], "operationId": "submit_kling_v3", "summary": "Run Kling V3 (kling-v3)", "description": "Ultra-high-definition storyboards with native audio.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_kling_v3" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/kling-v3\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"resolution\": \"1080p\",\n \"aspect_ratio\": \"16:9\",\n \"duration_ms\": 3000\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputKlingV3\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_kling_v3(\n input=InputKlingV3(\n aspect_ratio=\"16:9\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitKlingV3({\n input: {\n aspect_ratio: \"16:9\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/kling-v3-motion-control": { "post": { "tags": [ "Run a model" ], "operationId": "submit_kling_v3_motion_control", "summary": "Run Kling V3 Motion Control (kling-v3-motion-control)", "description": "Animate a character image to match the motion of a reference video. Standard tier for cost-effective generation.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_kling_v3_motion_control" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/kling-v3-motion-control\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"resolution\": \"720p\",\n \"source_video\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n },\n \"start_image\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputKlingV3MotionControl, InputKlingV3MotionControlStartImage_Url, InputKlingV3MotionControlSourceVideo_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_kling_v3motion_control(\n input=InputKlingV3MotionControl(\n start_image=InputKlingV3MotionControlStartImage_Url(\n url=\"url\",\n ),\n source_video=InputKlingV3MotionControlSourceVideo_Url(\n url=\"url\",\n ),\n resolution=\"720p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitKlingV3MotionControl({\n input: {\n start_image: {\n source: \"url\",\n url: \"url\"\n },\n source_video: {\n source: \"url\",\n url: \"url\"\n },\n resolution: \"720p\"\n }\n});\n" } ] } }, "/models/krea-2": { "post": { "tags": [ "Run a model" ], "operationId": "submit_krea_2", "summary": "Run Krea 2 (krea-2)", "description": "Krea 2 renders in whatever style you hand it \u2014 pass reference images and it takes on their palette, lighting and texture in a new scene. The smaller of the two, strongest on illustration, anime and painting.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_krea_2" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/krea-2\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputKrea2\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_krea2(\n input=InputKrea2(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitKrea2({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\"\n }\n});\n" } ] } }, "/models/ltx-2-3": { "post": { "tags": [ "Run a model" ], "operationId": "submit_ltx_2_3", "summary": "Run LTX-2.3 (ltx-2-3)", "description": "Clips up to 4K with synchronized native audio, for final output.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_ltx_2_3" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/ltx-2-3\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"auto\",\n \"duration_ms\": 6000,\n \"prompt\": \"prompt\",\n \"resolution\": \"1080p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputLtx23\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_ltx23(\n input=InputLtx23(\n prompt=\"prompt\",\n resolution=\"1080p\",\n duration_ms=1,\n aspect_ratio=\"auto\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitLtx23({\n input: {\n prompt: \"prompt\",\n resolution: \"1080p\",\n duration_ms: 1,\n aspect_ratio: \"auto\"\n }\n});\n" } ] } }, "/models/ltx-2-5": { "post": { "tags": [ "Run a model" ], "operationId": "submit_ltx_2_5", "summary": "Run LTX-2.5 (ltx-2-5)", "description": "Clips up to 20 seconds with synchronized native audio, on the quick path.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_ltx_2_5" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/ltx-2-5\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"auto\",\n \"prompt\": \"prompt\",\n \"resolution\": \"1080p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputLtx25\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_ltx25(\n input=InputLtx25(\n prompt=\"prompt\",\n resolution=\"1080p\",\n aspect_ratio=\"auto\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitLtx25({\n input: {\n prompt: \"prompt\",\n resolution: \"1080p\",\n aspect_ratio: \"auto\"\n }\n});\n" } ] } }, "/models/luma-ray-32": { "post": { "tags": [ "Run a model" ], "operationId": "submit_luma_ray_32", "summary": "Run Luma Ray 3.2 (luma-ray-32)", "description": "Cinematic motion with deliberate camera control, from a prompt.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_luma_ray_32" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/luma-ray-32\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"3:4\",\n \"duration_ms\": 5000,\n \"prompt\": \"prompt\",\n \"resolution\": \"540p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputLumaRay32\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_luma_ray32(\n input=InputLumaRay32(\n prompt=\"prompt\",\n aspect_ratio=\"3:4\",\n resolution=\"540p\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitLumaRay32({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"3:4\",\n resolution: \"540p\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/mai-image-2-5": { "post": { "tags": [ "Run a model" ], "operationId": "submit_mai_image_2_5", "summary": "Run MAI-Image-2.5 (mai-image-2-5)", "description": "Microsoft AI's MAI-Image-2.5: photorealistic generation and editing with strong in-image typography and design-ready output.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_mai_image_2_5" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/mai-image-2-5\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputMaiImage25\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_mai_image25(\n input=InputMaiImage25(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitMaiImage25({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\"\n }\n});\n" } ] } }, "/models/minimax-h3": { "post": { "tags": [ "Run a model" ], "operationId": "submit_minimax_h3", "summary": "Run MiniMax H3 (minimax-h3)", "description": "One model for every starting point \u2014 a prompt, a keyframe pair, or reference images that keep a subject consistent.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_minimax_h3" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/minimax-h3\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"duration_ms\": 5000,\n \"prompt\": \"prompt\",\n \"resolution\": \"480p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputMinimaxH3\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_minimax_h3(\n input=InputMinimaxH3(\n prompt=\"prompt\",\n resolution=\"480p\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitMinimaxH3({\n input: {\n prompt: \"prompt\",\n resolution: \"480p\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/minimax-h3-max-camera-controls": { "post": { "tags": [ "Run a model" ], "operationId": "submit_minimax_h3_max_camera_controls", "summary": "Run MiniMax H3 Max Camera Controls (minimax-h3-max-camera-controls)", "description": "Orbit, tilt, and dolly a camera through a single image along a path you key-frame in 3D.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_minimax_h3_max_camera_controls" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/minimax-h3-max-camera-controls\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"camera_trajectory\": [\n {\n \"time\": 0.0,\n \"azimuth\": 1.0,\n \"elevation\": -90.0,\n \"distance\": 1.0\n }\n ],\n \"duration_ms\": 5000,\n \"prompt\": \"prompt\",\n \"resolution\": \"480p\",\n \"start_image\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputMinimaxH3MaxCameraControls, InputMinimaxH3MaxCameraControlsStartImage_Url, InputMinimaxH3MaxCameraControlsCameraTrajectoryItem\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_minimax_h3max_camera_controls(\n input=InputMinimaxH3MaxCameraControls(\n prompt=\"prompt\",\n resolution=\"480p\",\n duration_ms=1,\n start_image=InputMinimaxH3MaxCameraControlsStartImage_Url(\n url=\"url\",\n ),\n camera_trajectory=[\n InputMinimaxH3MaxCameraControlsCameraTrajectoryItem(\n time=1.1,\n azimuth=1.1,\n elevation=1.1,\n distance=1.1,\n )\n ],\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitMinimaxH3MaxCameraControls({\n input: {\n prompt: \"prompt\",\n resolution: \"480p\",\n duration_ms: 1,\n start_image: {\n source: \"url\",\n url: \"url\"\n },\n camera_trajectory: [{\n time: 1.1,\n azimuth: 1.1,\n elevation: 1.1,\n distance: 1.1\n }]\n }\n});\n" } ] } }, "/models/minimax-h3-max-turbo": { "post": { "tags": [ "Run a model" ], "operationId": "submit_minimax_h3_max_turbo", "summary": "Run MiniMax H3 Max Turbo (minimax-h3-max-turbo)", "description": "MiniMax H3 Max Turbo \u2014 the same text and keyframe inputs, served faster and at half the price.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_minimax_h3_max_turbo" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/minimax-h3-max-turbo\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"duration_ms\": 5000,\n \"prompt\": \"prompt\",\n \"resolution\": \"480p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputMinimaxH3MaxTurbo\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_minimax_h3max_turbo(\n input=InputMinimaxH3MaxTurbo(\n prompt=\"prompt\",\n resolution=\"480p\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitMinimaxH3MaxTurbo({\n input: {\n prompt: \"prompt\",\n resolution: \"480p\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/minimax-hailuo-02": { "post": { "tags": [ "Run a model" ], "operationId": "submit_minimax_hailuo_02", "summary": "Run MiniMax Hailuo-02 (minimax-hailuo-02)", "description": "Everyday 1080p video with natural movement.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_minimax_hailuo_02" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/minimax-hailuo-02\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"duration_ms\": 6000,\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputMinimaxHailuo02\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_minimax_hailuo02(\n input=InputMinimaxHailuo02(\n prompt=\"prompt\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitMinimaxHailuo02({\n input: {\n prompt: \"prompt\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/minimax-hailuo-23": { "post": { "tags": [ "Run a model" ], "operationId": "submit_minimax_hailuo_23", "summary": "Run MiniMax Hailuo 2.3 (minimax-hailuo-23)", "description": "Everyday 1080p video with natural movement.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_minimax_hailuo_23" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/minimax-hailuo-23\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"duration_ms\": 6000,\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputMinimaxHailuo23\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_minimax_hailuo23(\n input=InputMinimaxHailuo23(\n prompt=\"prompt\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitMinimaxHailuo23({\n input: {\n prompt: \"prompt\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/minimax-speech-25-hd-preview": { "post": { "tags": [ "Run a model" ], "operationId": "submit_minimax_speech_25_hd_preview", "summary": "Run MiniMax Speech-2.5 HD Preview (minimax-speech-25-hd-preview)", "description": "The high-fidelity tier \u2014 closest voice likeness, across 40+ languages.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_minimax_speech_25_hd_preview" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/minimax-speech-25-hd-preview\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"text\": \"text\",\n \"voice_id\": \"voice_id\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputMinimaxSpeech25HdPreview\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_minimax_speech25hd_preview(\n input=InputMinimaxSpeech25HdPreview(\n text=\"text\",\n voice_id=\"voice_id\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitMinimaxSpeech25HdPreview({\n input: {\n text: \"text\",\n voice_id: \"voice_id\"\n }\n});\n" } ] } }, "/models/minimax-speech-25-turbo-preview": { "post": { "tags": [ "Run a model" ], "operationId": "submit_minimax_speech_25_turbo_preview", "summary": "Run MiniMax Speech-2.5 Turbo Preview (minimax-speech-25-turbo-preview)", "description": "The value tier \u2014 natural English delivery across 40+ languages, at a lower rate.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_minimax_speech_25_turbo_preview" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/minimax-speech-25-turbo-preview\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"text\": \"text\",\n \"voice_id\": \"voice_id\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputMinimaxSpeech25TurboPreview\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_minimax_speech25turbo_preview(\n input=InputMinimaxSpeech25TurboPreview(\n text=\"text\",\n voice_id=\"voice_id\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitMinimaxSpeech25TurboPreview({\n input: {\n text: \"text\",\n voice_id: \"voice_id\"\n }\n});\n" } ] } }, "/models/muse-image": { "post": { "tags": [ "Run a model" ], "operationId": "submit_muse_image", "summary": "Run Muse Image (muse-image)", "description": "Meta's Muse Image: an agentic image model that plans before it renders, with faithful instruction-following, accurate in-image text, and edits that change only what you ask.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_muse_image" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/muse-image\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"adaptive\",\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputMuseImage\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_muse_image(\n input=InputMuseImage(\n prompt=\"prompt\",\n aspect_ratio=\"adaptive\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitMuseImage({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"adaptive\"\n }\n});\n" } ] } }, "/models/nano-banana": { "post": { "tags": [ "Run a model" ], "operationId": "submit_nano_banana", "summary": "Run Nano Banana (nano-banana)", "description": "Reference-guided stills that hold a character or product across a set.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_nano_banana" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/nano-banana\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\",\n \"resolution\": \"1K\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputNanoBanana\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_nano_banana(\n input=InputNanoBanana(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n resolution=\"1K\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitNanoBanana({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n resolution: \"1K\"\n }\n});\n" } ] } }, "/models/nano-banana-2": { "post": { "tags": [ "Run a model" ], "operationId": "submit_nano_banana_2", "summary": "Run Nano Banana 2 (nano-banana-2)", "description": "Multi-subject stills up to 4K \u2014 hand it several references and it keeps each one recognizable.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_nano_banana_2" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/nano-banana-2\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"adaptive\",\n \"prompt\": \"prompt\",\n \"resolution\": \"512px\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputNanoBanana2\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_nano_banana2(\n input=InputNanoBanana2(\n prompt=\"prompt\",\n aspect_ratio=\"adaptive\",\n resolution=\"512px\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitNanoBanana2({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"adaptive\",\n resolution: \"512px\"\n }\n});\n" } ] } }, "/models/nano-banana-pro": { "post": { "tags": [ "Run a model" ], "operationId": "submit_nano_banana_pro", "summary": "Run Nano Banana Pro (nano-banana-pro)", "description": "The reasoning-heavy tier \u2014 dense prompts, mixed references, and style transfer up to 4K.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_nano_banana_pro" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/nano-banana-pro\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"adaptive\",\n \"prompt\": \"prompt\",\n \"resolution\": \"1K\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputNanoBananaPro\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_nano_banana_pro(\n input=InputNanoBananaPro(\n prompt=\"prompt\",\n aspect_ratio=\"adaptive\",\n resolution=\"1K\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitNanoBananaPro({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"adaptive\",\n resolution: \"1K\"\n }\n});\n" } ] } }, "/models/omnihuman-15": { "post": { "tags": [ "Run a model" ], "operationId": "submit_omnihuman_15", "summary": "Run Omnihuman 1.5 (omnihuman-15)", "description": "Creates vivid, emotional character videos driven entirely by your audio.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_omnihuman_15" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/omnihuman-15\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"audio\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n },\n \"resolution\": \"720p\",\n \"start_image\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputOmnihuman15, InputOmnihuman15StartImage_Url, InputOmnihuman15Audio_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_omnihuman15(\n input=InputOmnihuman15(\n resolution=\"720p\",\n start_image=InputOmnihuman15StartImage_Url(\n url=\"url\",\n ),\n audio=InputOmnihuman15Audio_Url(\n url=\"url\",\n ),\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitOmnihuman15({\n input: {\n resolution: \"720p\",\n start_image: {\n source: \"url\",\n url: \"url\"\n },\n audio: {\n source: \"url\",\n url: \"url\"\n }\n }\n});\n" } ] } }, "/models/pixverse-v6": { "post": { "tags": [ "Run a model" ], "operationId": "submit_pixverse_v6", "summary": "Run PixVerse V6 (pixverse-v6)", "description": "Stylized 1080p clips up to 15 seconds, with native audio.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_pixverse_v6" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/pixverse-v6\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"duration_ms\": 1000,\n \"prompt\": \"prompt\",\n \"resolution\": \"360p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputPixverseV6\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_pixverse_v6(\n input=InputPixverseV6(\n prompt=\"prompt\",\n resolution=\"360p\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitPixverseV6({\n input: {\n prompt: \"prompt\",\n resolution: \"360p\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/qwen-image-2": { "post": { "tags": [ "Run a model" ], "operationId": "submit_qwen_image_2", "summary": "Run Qwen Image 2.0 (qwen-image-2)", "description": "Alibaba's Qwen-Image-2.0, tuned for speed. Native 2K output with professional in-image text rendering, for rapid iteration.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_qwen_image_2" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/qwen-image-2\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\",\n \"resolution\": \"540p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputQwenImage2\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_qwen_image2(\n input=InputQwenImage2(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n resolution=\"540p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitQwenImage2({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n resolution: \"540p\"\n }\n});\n" } ] } }, "/models/recraft-v3": { "post": { "tags": [ "Run a model" ], "operationId": "submit_recraft_v3", "summary": "Run Recraft V3 (recraft-v3)", "description": "Vector-clean graphics and crisp logos on demand.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_recraft_v3" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/recraft-v3\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"prompt\": \"prompt\",\n \"resolution\": \"540p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputRecraftV3\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_recraft_v3(\n input=InputRecraftV3(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n resolution=\"540p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitRecraftV3({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\",\n resolution: \"540p\"\n }\n});\n" } ] } }, "/models/reve-21": { "post": { "tags": [ "Run a model" ], "operationId": "submit_reve_21", "summary": "Run Reve 2.1 (reve-21)", "description": "Generate images from a text prompt with strong prompt adherence, layout intelligence, and accurate text rendering\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_reve_21" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/reve-21\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"4:1\",\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputReve21\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_reve21(\n input=InputReve21(\n prompt=\"prompt\",\n aspect_ratio=\"4:1\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitReve21({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"4:1\"\n }\n});\n" } ] } }, "/models/reve-21-edit": { "post": { "tags": [ "Run a model" ], "operationId": "submit_reve_21_edit", "summary": "Run Reve 2.1 Edit (reve-21-edit)", "description": "Edit one source image from a natural-language instruction, keeping the rest of the image intact\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_reve_21_edit" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/reve-21-edit\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"4:1\",\n \"images\": [\n {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n ],\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputReve21Edit, InputReve21EditImagesItem_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_reve21edit(\n input=InputReve21Edit(\n prompt=\"prompt\",\n aspect_ratio=\"4:1\",\n images=[\n InputReve21EditImagesItem_Url(\n url=\"url\",\n )\n ],\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitReve21Edit({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"4:1\",\n images: [{\n source: \"url\",\n url: \"url\"\n }]\n }\n});\n" } ] } }, "/models/reve-21-remix": { "post": { "tags": [ "Run a model" ], "operationId": "submit_reve_21_remix", "summary": "Run Reve 2.1 Remix (reve-21-remix)", "description": "Compose up to eight reference images into a new image from a text prompt\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_reve_21_remix" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/reve-21-remix\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"4:1\",\n \"images\": [\n {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n ],\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputReve21Remix, InputReve21RemixImagesItem_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_reve21remix(\n input=InputReve21Remix(\n prompt=\"prompt\",\n aspect_ratio=\"4:1\",\n images=[\n InputReve21RemixImagesItem_Url(\n url=\"url\",\n )\n ],\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitReve21Remix({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"4:1\",\n images: [{\n source: \"url\",\n url: \"url\"\n }]\n }\n});\n" } ] } }, "/models/sana": { "post": { "tags": [ "Run a model" ], "operationId": "submit_sana", "summary": "Run Sana (sana)", "description": "Lightning-fast and cheap for simple product shots or everyday content.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_sana" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/sana\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"prompt\": \"prompt\",\n \"resolution\": \"540p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputSana\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_sana(\n input=InputSana(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n resolution=\"540p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitSana({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\",\n resolution: \"540p\"\n }\n});\n" } ] } }, "/models/seedance-15-pro": { "post": { "tags": [ "Run a model" ], "operationId": "submit_seedance_15_pro", "summary": "Run Seedance 1.5 Pro (seedance-15-pro)", "description": "Keyframe-driven video with native audio, from a start frame, an end frame, or both.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_seedance_15_pro" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/seedance-15-pro\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"duration_ms\": 4000,\n \"prompt\": \"prompt\",\n \"resolution\": \"480p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputSeedance15Pro\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_seedance15pro(\n input=InputSeedance15Pro(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n resolution=\"480p\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitSeedance15Pro({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\",\n resolution: \"480p\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/seedance-20": { "post": { "tags": [ "Run a model" ], "operationId": "submit_seedance_20", "summary": "Run Seedance 2.0 (seedance-20)", "description": "Reference-driven video up to 4K with native audio \u2014 hold a look across shots with reference images, clips, or audio.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_seedance_20" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/seedance-20\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"duration_ms\": 4000,\n \"prompt\": \"prompt\",\n \"resolution\": \"4K\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputSeedance20\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_seedance20(\n input=InputSeedance20(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n resolution=\"4K\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitSeedance20({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\",\n resolution: \"4K\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/seedance-20-mini": { "post": { "tags": [ "Run a model" ], "operationId": "submit_seedance_20_mini", "summary": "Run Seedance 2.0 Mini (seedance-20-mini)", "description": "The lightest Seedance tier \u2014 short reference-driven clips at 480p and 720p.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_seedance_20_mini" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/seedance-20-mini\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"duration_ms\": 4000,\n \"prompt\": \"prompt\",\n \"resolution\": \"480p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputSeedance20Mini\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_seedance20mini(\n input=InputSeedance20Mini(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n resolution=\"480p\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitSeedance20Mini({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\",\n resolution: \"480p\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/seedance-25": { "post": { "tags": [ "Run a model" ], "operationId": "submit_seedance_25", "summary": "Run Seedance 2.5 (seedance-25)", "description": "Reference-driven video up to 30 seconds at 1080p, with native audio.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_seedance_25" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/seedance-25\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"duration_ms\": -1,\n \"prompt\": \"prompt\",\n \"resolution\": \"480p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputSeedance25\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_seedance25(\n input=InputSeedance25(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n resolution=\"480p\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitSeedance25({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\",\n resolution: \"480p\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/seedream-40": { "post": { "tags": [ "Run a model" ], "operationId": "submit_seedream_40", "summary": "Run Seedream 4.0 (seedream-40)", "description": "Quick, reference-aware stills for professional work on a tight turnaround.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_seedream_40" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/seedream-40\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"prompt\": \"prompt\",\n \"resolution\": \"1080p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputSeedream40\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_seedream40(\n input=InputSeedream40(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n resolution=\"1080p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitSeedream40({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\",\n resolution: \"1080p\"\n }\n});\n" } ] } }, "/models/seedream-45": { "post": { "tags": [ "Run a model" ], "operationId": "submit_seedream_45", "summary": "Run Seedream 4.5 (seedream-45)", "description": "Finer detail and steadier composition than 4.0, with support for several references at once.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_seedream_45" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/seedream-45\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"prompt\": \"prompt\",\n \"resolution\": \"1440p (2K QHD)\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputSeedream45\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_seedream45(\n input=InputSeedream45(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n resolution=\"1440p (2K QHD)\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitSeedream45({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\",\n resolution: \"1440p (2K QHD)\"\n }\n});\n" } ] } }, "/models/seedream-50-lite": { "post": { "tags": [ "Run a model" ], "operationId": "submit_seedream_50_lite", "summary": "Run Seedream 5.0 Lite (seedream-50-lite)", "description": "Sharp 2K and 4K stills from a prompt, at the light tier's price.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_seedream_50_lite" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/seedream-50-lite\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"prompt\": \"prompt\",\n \"resolution\": \"1440p (2K QHD)\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputSeedream50Lite\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_seedream50lite(\n input=InputSeedream50Lite(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n resolution=\"1440p (2K QHD)\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitSeedream50Lite({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\",\n resolution: \"1440p (2K QHD)\"\n }\n});\n" } ] } }, "/models/seedream-50-pro": { "post": { "tags": [ "Run a model" ], "operationId": "submit_seedream_50_pro", "summary": "Run Seedream 5.0 Pro (seedream-50-pro)", "description": "The top Seedream tier \u2014 layer-separable output and strong multilingual in-image text, up to 2K.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_seedream_50_pro" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/seedream-50-pro\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"1:1\",\n \"prompt\": \"prompt\",\n \"resolution\": \"1080p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputSeedream50Pro\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_seedream50pro(\n input=InputSeedream50Pro(\n prompt=\"prompt\",\n aspect_ratio=\"1:1\",\n resolution=\"1080p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitSeedream50Pro({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"1:1\",\n resolution: \"1080p\"\n }\n});\n" } ] } }, "/models/sora-2-pro": { "post": { "tags": [ "Run a model" ], "operationId": "submit_sora_2_pro", "summary": "Run Sora 2 Pro (sora-2-pro)", "description": "For complex, narrative-driven videos with remarkable consistency and realistic character-world interaction.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_sora_2_pro" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/sora-2-pro\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"duration_ms\": 4000,\n \"prompt\": \"prompt\",\n \"resolution\": \"720p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputSora2Pro\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_sora2pro(\n input=InputSora2Pro(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n resolution=\"720p\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitSora2Pro({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n resolution: \"720p\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/topaz-image-upscaler": { "post": { "tags": [ "Run a model" ], "operationId": "submit_topaz_image_upscaler", "summary": "Run Topaz Gigapixel (topaz-image-upscaler)", "description": "Use the powerful and accurate Topaz image enhancer to upscale and enhance your images.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_topaz_image_upscaler" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/topaz-image-upscaler\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"source_image\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n },\n \"target_resolution\": \"1080p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputTopazImageUpscaler, InputTopazImageUpscalerSourceImage_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_topaz_image_upscaler(\n input=InputTopazImageUpscaler(\n source_image=InputTopazImageUpscalerSourceImage_Url(\n url=\"url\",\n ),\n target_resolution=\"1080p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitTopazImageUpscaler({\n input: {\n source_image: {\n source: \"url\",\n url: \"url\"\n },\n target_resolution: \"1080p\"\n }\n});\n" } ] } }, "/models/topaz-image-upscaler-transparency": { "post": { "tags": [ "Run a model" ], "operationId": "submit_topaz_image_upscaler_transparency", "summary": "Run Topaz Transparency (topaz-image-upscaler-transparency)", "description": "Upscale a logo, sticker, or cutout 4x with its transparency intact. Returns PNG.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_topaz_image_upscaler_transparency" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/topaz-image-upscaler-transparency\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"source_image\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputTopazImageUpscalerTransparency, InputTopazImageUpscalerTransparencySourceImage_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_topaz_image_upscaler_transparency(\n input=InputTopazImageUpscalerTransparency(\n source_image=InputTopazImageUpscalerTransparencySourceImage_Url(\n url=\"url\",\n ),\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitTopazImageUpscalerTransparency({\n input: {\n source_image: {\n source: \"url\",\n url: \"url\"\n }\n }\n});\n" } ] } }, "/models/topaz-image-upscaler-wonder": { "post": { "tags": [ "Run a model" ], "operationId": "submit_topaz_image_upscaler_wonder", "summary": "Run Topaz Wonder (topaz-image-upscaler-wonder)", "description": "Generative upscaling with realistic detail, precise text, and clean graphics \u2014 Topaz's highest-quality image upscaler.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_topaz_image_upscaler_wonder" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/topaz-image-upscaler-wonder\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"source_image\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n },\n \"target_resolution\": \"1080p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputTopazImageUpscalerWonder, InputTopazImageUpscalerWonderSourceImage_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_topaz_image_upscaler_wonder(\n input=InputTopazImageUpscalerWonder(\n source_image=InputTopazImageUpscalerWonderSourceImage_Url(\n url=\"url\",\n ),\n target_resolution=\"1080p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitTopazImageUpscalerWonder({\n input: {\n source_image: {\n source: \"url\",\n url: \"url\"\n },\n target_resolution: \"1080p\"\n }\n});\n" } ] } }, "/models/topaz-video-upscaler": { "post": { "tags": [ "Run a model" ], "operationId": "submit_topaz_video_upscaler", "summary": "Run Topaz Proteus (topaz-video-upscaler)", "description": "Precision upscaling that cleans compression and noise while staying faithful to the source.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_topaz_video_upscaler" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/topaz-video-upscaler\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"resolution\": \"1080p\",\n \"source_video\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputTopazVideoUpscaler, InputTopazVideoUpscalerSourceVideo_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_topaz_video_upscaler(\n input=InputTopazVideoUpscaler(\n source_video=InputTopazVideoUpscalerSourceVideo_Url(\n url=\"url\",\n ),\n resolution=\"1080p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitTopazVideoUpscaler({\n input: {\n source_video: {\n source: \"url\",\n url: \"url\"\n },\n resolution: \"1080p\"\n }\n});\n" } ] } }, "/models/topaz-video-upscaler-hyperion-2-5": { "post": { "tags": [ "Run a model" ], "operationId": "submit_topaz_video_upscaler_hyperion_2_5", "summary": "Run Topaz Hyperion 2.5 HDR (topaz-video-upscaler-hyperion-2-5)", "description": "Convert SDR video to 10-bit HDR with richer highlights, color, and tonal separation. The output keeps the source resolution.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_topaz_video_upscaler_hyperion_2_5" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/topaz-video-upscaler-hyperion-2-5\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"source_video\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputTopazVideoUpscalerHyperion25, InputTopazVideoUpscalerHyperion25SourceVideo_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_topaz_video_upscaler_hyperion25(\n input=InputTopazVideoUpscalerHyperion25(\n source_video=InputTopazVideoUpscalerHyperion25SourceVideo_Url(\n url=\"url\",\n ),\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitTopazVideoUpscalerHyperion25({\n input: {\n source_video: {\n source: \"url\",\n url: \"url\"\n }\n }\n});\n" } ] } }, "/models/topaz-video-upscaler-starlight-fast": { "post": { "tags": [ "Run a model" ], "operationId": "submit_topaz_video_upscaler_starlight_fast", "summary": "Run Topaz Starlight Fast (topaz-video-upscaler-starlight-fast)", "description": "Faster generative diffusion upscaling at half the cost of Starlight Precise.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_topaz_video_upscaler_starlight_fast" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/topaz-video-upscaler-starlight-fast\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"resolution\": \"1080p\",\n \"source_video\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputTopazVideoUpscalerStarlightFast, InputTopazVideoUpscalerStarlightFastSourceVideo_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_topaz_video_upscaler_starlight_fast(\n input=InputTopazVideoUpscalerStarlightFast(\n source_video=InputTopazVideoUpscalerStarlightFastSourceVideo_Url(\n url=\"url\",\n ),\n resolution=\"1080p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitTopazVideoUpscalerStarlightFast({\n input: {\n source_video: {\n source: \"url\",\n url: \"url\"\n },\n resolution: \"1080p\"\n }\n});\n" } ] } }, "/models/topaz-video-upscaler-starlight-hq": { "post": { "tags": [ "Run a model" ], "operationId": "submit_topaz_video_upscaler_starlight_hq", "summary": "Run Topaz Starlight HQ (topaz-video-upscaler-starlight-hq)", "description": "Generative diffusion upscaling balancing detail and sharpness for medium-to-high quality sources.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_topaz_video_upscaler_starlight_hq" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/topaz-video-upscaler-starlight-hq\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"resolution\": \"1080p\",\n \"source_video\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputTopazVideoUpscalerStarlightHq, InputTopazVideoUpscalerStarlightHqSourceVideo_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_topaz_video_upscaler_starlight_hq(\n input=InputTopazVideoUpscalerStarlightHq(\n source_video=InputTopazVideoUpscalerStarlightHqSourceVideo_Url(\n url=\"url\",\n ),\n resolution=\"1080p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitTopazVideoUpscalerStarlightHq({\n input: {\n source_video: {\n source: \"url\",\n url: \"url\"\n },\n resolution: \"1080p\"\n }\n});\n" } ] } }, "/models/topaz-video-upscaler-starlight-precise": { "post": { "tags": [ "Run a model" ], "operationId": "submit_topaz_video_upscaler_starlight_precise", "summary": "Run Topaz Starlight Precise (topaz-video-upscaler-starlight-precise)", "description": "Generative diffusion upscaling for AI-generated and archival video with realistic faces, textures, and text.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_topaz_video_upscaler_starlight_precise" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/topaz-video-upscaler-starlight-precise\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"resolution\": \"1080p\",\n \"source_video\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputTopazVideoUpscalerStarlightPrecise, InputTopazVideoUpscalerStarlightPreciseSourceVideo_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_topaz_video_upscaler_starlight_precise(\n input=InputTopazVideoUpscalerStarlightPrecise(\n source_video=InputTopazVideoUpscalerStarlightPreciseSourceVideo_Url(\n url=\"url\",\n ),\n resolution=\"1080p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitTopazVideoUpscalerStarlightPrecise({\n input: {\n source_video: {\n source: \"url\",\n url: \"url\"\n },\n resolution: \"1080p\"\n }\n});\n" } ] } }, "/models/veed-fabric-10": { "post": { "tags": [ "Run a model" ], "operationId": "submit_veed_fabric_10", "summary": "Run VEED Fabric 1.0 (veed-fabric-10)", "description": "Talking video with natural lip-sync and expressive animation.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_veed_fabric_10" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/veed-fabric-10\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"audio\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n },\n \"prompt\": \"prompt\",\n \"resolution\": \"480p\",\n \"start_image\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputVeedFabric10, InputVeedFabric10StartImage_Url, InputVeedFabric10Audio_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_veed_fabric10(\n input=InputVeedFabric10(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n resolution=\"480p\",\n start_image=InputVeedFabric10StartImage_Url(\n url=\"url\",\n ),\n audio=InputVeedFabric10Audio_Url(\n url=\"url\",\n ),\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitVeedFabric10({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n resolution: \"480p\",\n start_image: {\n source: \"url\",\n url: \"url\"\n },\n audio: {\n source: \"url\",\n url: \"url\"\n }\n }\n});\n" } ] } }, "/models/veed-video-background-removal": { "post": { "tags": [ "Run a model" ], "operationId": "submit_veed_video_background_removal", "summary": "Run VEED Video Background Removal (veed-video-background-removal)", "description": "Remove a video's background and return transparent WebM.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_veed_video_background_removal" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/veed-video-background-removal\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"source_video\": {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputVeedVideoBackgroundRemoval, InputVeedVideoBackgroundRemovalSourceVideo_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_veed_video_background_removal(\n input=InputVeedVideoBackgroundRemoval(\n source_video=InputVeedVideoBackgroundRemovalSourceVideo_Url(\n url=\"url\",\n ),\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitVeedVideoBackgroundRemoval({\n input: {\n source_video: {\n source: \"url\",\n url: \"url\"\n }\n }\n});\n" } ] } }, "/models/veo-2": { "post": { "tags": [ "Run a model" ], "operationId": "submit_veo_2", "summary": "Run Veo 2 (veo-2)", "description": "Google's earlier cinematic generator, kept for existing workflows.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_veo_2" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/veo-2\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"prompt\": \"prompt\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputVeo2\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_veo2(\n input=InputVeo2(\n prompt=\"prompt\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitVeo2({\n input: {\n prompt: \"prompt\"\n }\n});\n" } ] } }, "/models/veo-3": { "post": { "tags": [ "Run a model" ], "operationId": "submit_veo_3", "summary": "Run Veo 3 (veo-3)", "description": "Hollywood-grade, cinematic video straight from text\u2014your go-to for hero campaigns.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_veo_3" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/veo-3\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"duration_ms\": 4000,\n \"prompt\": \"prompt\",\n \"resolution\": \"720p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputVeo3\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_veo3(\n input=InputVeo3(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n resolution=\"720p\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitVeo3({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n resolution: \"720p\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/veo-31": { "post": { "tags": [ "Run a model" ], "operationId": "submit_veo_31", "summary": "Run Veo 3.1 (veo-31)", "description": "For unparalleled detail and nuance, perfect for when your vision requires the best possible quality.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_veo_31" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/veo-31\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"prompt\": \"prompt\",\n \"resolution\": \"720p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputVeo31\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_veo31(\n input=InputVeo31(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n resolution=\"720p\",\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitVeo31({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n resolution: \"720p\"\n }\n});\n" } ] } }, "/models/vidu-q3": { "post": { "tags": [ "Run a model" ], "operationId": "submit_vidu_q3", "summary": "Run Vidu Q3 (vidu-q3)", "description": "The longest clips in the catalog \u2014 up to 16 seconds with native dialogue and sound, from a text prompt, from a start frame, or between a start and end frame\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_vidu_q3" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/vidu-q3\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"duration_ms\": 1000,\n \"prompt\": \"prompt\",\n \"resolution\": \"540p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputViduQ3\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_vidu_q3(\n input=InputViduQ3(\n prompt=\"prompt\",\n resolution=\"540p\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitViduQ3({\n input: {\n prompt: \"prompt\",\n resolution: \"540p\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/vidu-q3-reference": { "post": { "tags": [ "Run a model" ], "operationId": "submit_vidu_q3_reference", "summary": "Run Vidu Q3 Reference (vidu-q3-reference)", "description": "Keep up to four subjects consistent across a clip from reference images.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_vidu_q3_reference" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/vidu-q3-reference\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"16:9\",\n \"duration_ms\": 1000,\n \"images\": [\n {\n \"source\": \"url\",\n \"url\": \"https://example.com\"\n }\n ],\n \"prompt\": \"prompt\",\n \"resolution\": \"540p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputViduQ3Reference, InputViduQ3ReferenceImagesItem_Url\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_vidu_q3reference(\n input=InputViduQ3Reference(\n prompt=\"prompt\",\n aspect_ratio=\"16:9\",\n resolution=\"540p\",\n duration_ms=1,\n images=[\n InputViduQ3ReferenceImagesItem_Url(\n url=\"url\",\n )\n ],\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitViduQ3Reference({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"16:9\",\n resolution: \"540p\",\n duration_ms: 1,\n images: [{\n source: \"url\",\n url: \"url\"\n }]\n }\n});\n" } ] } }, "/models/wan-2-7": { "post": { "tags": [ "Run a model" ], "operationId": "submit_wan_2_7", "summary": "Run Wan 2.7 (wan-2-7)", "description": "Wan 2.7 video with native audio \u2014 from a text prompt, from a first frame with an optional last frame, or from reference images that keep subjects consistent\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_wan_2_7" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/wan-2-7\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"duration_ms\": 2000,\n \"prompt\": \"prompt\",\n \"resolution\": \"720p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputWan27\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_wan27(\n input=InputWan27(\n prompt=\"prompt\",\n resolution=\"720p\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitWan27({\n input: {\n prompt: \"prompt\",\n resolution: \"720p\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/wan-3-0": { "post": { "tags": [ "Run a model" ], "operationId": "submit_wan_3_0", "summary": "Run Wan 3.0 (wan-3-0)", "description": "Wan 3.0 video with native audio, up to 30 seconds in one shot \u2014 from a text prompt, from a first frame with an optional last frame, or from reference images that keep subjects consistent\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody_wan_3_0" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/wan-3-0\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"aspect_ratio\": \"adaptive\",\n \"duration_ms\": 2000,\n \"prompt\": \"prompt\",\n \"resolution\": \"480p\"\n }\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra, InputWan30\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit_wan30(\n input=InputWan30(\n prompt=\"prompt\",\n aspect_ratio=\"adaptive\",\n resolution=\"480p\",\n duration_ms=1,\n ),\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submitWan30({\n input: {\n prompt: \"prompt\",\n aspect_ratio: \"adaptive\",\n resolution: \"480p\",\n duration_ms: 1\n }\n});\n" } ] } }, "/models/{model}": { "get": { "tags": [ "Models" ], "summary": "Get Model", "operationId": "models_get", "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "description": "The model's public id (`GET /v3/models`).", "title": "Model" }, "description": "The model's public id (`GET /v3/models`)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelDetail" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/models/{model}\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.models.get(\n model=\"model\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.models.get(\"model\");\n" } ] }, "post": { "tags": [ "Run a model" ], "operationId": "submit", "summary": "Run a model by id", "description": "Runs any model in the catalog by its public id, with `input` passed through untyped \u2014 the same call the typed operations below make, minus the compile-time schema.\n\nReach for it when the model is not known ahead of time: a client generated before a model shipped can still run it, and an id read from `GET /v3/models` at runtime needs no regeneration. Prefer the typed operation whenever your client already has one \u2014 `input` here is validated against the same published schema (`GET /v3/models/{model}`), so a bad field is a `400` at submit rather than an error before the call.\n\nSubmits an asynchronous job and returns `202` with a job id. Fetch the result at `GET /v3/jobs/{job_id}` \u2014 each item in its `outputs[]` follows the `OutputItem` schema \u2014 or track progress via `GET /v3/jobs/{job_id}/status` / the SSE stream at `GET /v3/jobs/{job_id}/stream`.", "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The model's public id (`GET /v3/models`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBody" } } } }, "responses": { "202": { "description": "Accepted. The job runs asynchronously; poll `status_url` / `result_url` from the ack.", "headers": { "Location": { "description": "Path of the job resource this submit created \u2014 the same value as the ack's `result_url`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } } } } }, "402": { "description": "The API wallet cannot cover this request. `error.billing` carries the balance, the price, and where to add funds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } }, "422": { "description": "Moderation refused the request's content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "moderation_failed": { "summary": "A reference image was refused by moderation", "value": { "error": { "code": "MODERATION_FAILED", "message": "Image failed moderation.", "retryable": false } } } } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/{model}\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {}\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.jobs.submit(\n model=\"model\",\n input={\n \"key\": \"value\"\n },\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.jobs.submit(\"model\", {\n input: {\n \"key\": \"value\"\n }\n});\n" } ] } }, "/models/{model}/jobs": { "get": { "tags": [ "Models" ], "summary": "List Model Jobs", "operationId": "models_list_model_jobs", "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "description": "The model's public id (`GET /v3/models`).", "title": "Model" }, "description": "The model's public id (`GET /v3/models`)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum items per page.", "default": 20, "title": "Limit" }, "description": "Maximum items per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor from the previous page's `next_cursor`; omit for the first page.", "title": "Cursor" }, "description": "Opaque cursor from the previous page's `next_cursor`; omit for the first page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobListResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/models/{model}/jobs\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.models.list_model_jobs(\n model=\"model\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst pageableResponse = await client.models.listModelJobs(\"model\");\nfor await (const item of pageableResponse) {\n console.log(item);\n}\n\n// Or you can manually iterate page-by-page\nlet page = await client.models.listModelJobs(\"model\");\nwhile (page.hasNextPage()) {\n page = await page.getNextPage();\n}\n\n// You can also access the underlying response\nconst response = page.response;\n" } ] } }, "/models/{model}/voices": { "get": { "tags": [ "Models" ], "summary": "List Model Voices", "description": "Voices this model accepts \u2014 the shared library, plus the caller's own cloned voices when the request carries credentials.", "operationId": "models_list_voices", "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "description": "The model's public id (`GET /v3/models`).", "title": "Model" }, "description": "The model's public id (`GET /v3/models`)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceListResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ {}, { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/models/{model}/voices\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.models.list_voices(\n model=\"model\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.models.listVoices(\"model\");\n" } ] } }, "/models/{model}/voices/search": { "get": { "tags": [ "Models" ], "summary": "Search Model Voices", "description": "The voices this model accepts, ranked against a description \u2014 the whole shared library, including the voices the listing does not return.", "operationId": "models_search_voices", "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "description": "The model's public id (`GET /v3/models`).", "title": "Model" }, "description": "The model's public id (`GET /v3/models`)." }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "What the voice should sound like, in plain words \u2014 \"warm british narrator\", \"energetic young announcer\". Matched against the whole library for this model's provider, not just the voices `GET /v3/models/{model}/voices` returns.", "title": "Q" }, "description": "What the voice should sound like, in plain words \u2014 \"warm british narrator\", \"energetic young announcer\". Matched against the whole library for this model's provider, not just the voices `GET /v3/models/{model}/voices` returns." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum voices to return. Applies to the whole response.", "default": 20, "title": "Limit" }, "description": "Maximum voices to return. Applies to the whole response." }, { "name": "gender", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/VoiceGender" }, { "type": "null" } ], "description": "Only voices curated with this gender.", "title": "Gender" }, "description": "Only voices curated with this gender." }, { "name": "language", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 8 }, { "type": "null" } ], "description": "Only voices curated for this language, as an ISO 639-1 two-letter code (`en`, `es`, `fr`).", "title": "Language" }, "description": "Only voices curated for this language, as an ISO 639-1 two-letter code (`en`, `es`, `fr`)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceListResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/models/{model}/voices/search\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.models.search_voices(\n model=\"model\",\n q=\"q\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.models.searchVoices(\"model\", {\n q: \"q\"\n});\n" } ] } }, "/models/{model}/openapi.json": { "get": { "tags": [ "Models" ], "summary": "Get Model Openapi", "description": "A standalone one-operation OpenAPI spec for this model's submit call.", "operationId": "models_get_openapi", "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "description": "The model's public id (`GET /v3/models`).", "title": "Model" }, "description": "The model's public id (`GET /v3/models`)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Response Models Get Openapi" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/models/{model}/openapi.json\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.models.get_openapi(\n model=\"model\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.models.getOpenapi(\"model\");\n" } ] } }, "/models/{model}/estimate": { "post": { "tags": [ "Models" ], "summary": "Estimate", "operationId": "models_estimate", "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "description": "The model's public id (`GET /v3/models`).", "title": "Model" }, "description": "The model's public id (`GET /v3/models`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/models/{model}/estimate\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {}\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.models.estimate(\n model=\"model\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.models.estimate(\"model\");\n" } ] } }, "/keys": { "post": { "tags": [ "Access" ], "summary": "Create Key", "operationId": "keys_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyCreateResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/keys\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"name\",\n \"scopes\": [\n \"jobs:read\"\n ],\n \"kind\": \"personal\",\n \"workspace_id\": \"workspace_id\",\n \"expires_at\": \"2026-01-01T00:00:00Z\"\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.keys.create()\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.keys.create();\n" } ] }, "get": { "tags": [ "Access" ], "summary": "List Keys", "operationId": "keys_list", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "List keys of this workspace; omitted means the authenticating key's workspace.", "title": "Workspace Id" }, "description": "List keys of this workspace; omitted means the authenticating key's workspace." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyListResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/keys\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.keys.list()\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.keys.list();\n" } ] } }, "/keys/{key_id}/rotate": { "post": { "tags": [ "Access" ], "summary": "Rotate Key", "operationId": "keys_rotate", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The key's public identifier.", "title": "Key Id" }, "description": "The key's public identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyRotateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyRotateResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/keys/{key_id}/rotate\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"grace_period_seconds\": 0.0\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.keys.rotate(\n key_id=\"key_id\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.keys.rotate(\"key_id\");\n" } ] } }, "/keys/{key_id}": { "delete": { "tags": [ "Access" ], "summary": "Revoke Key", "operationId": "keys_revoke", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The key's public identifier.", "title": "Key Id" }, "description": "The key's public identifier." } ], "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X DELETE \"https://api.hedra.com/v3/keys/{key_id}\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.keys.revoke(\n key_id=\"key_id\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.keys.revoke(\"key_id\");\n" } ] } }, "/tokens": { "post": { "tags": [ "Access" ], "summary": "Create Token", "operationId": "tokens_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/tokens\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"ttl_seconds\": 1,\n \"scopes\": [\n \"jobs:read\"\n ]\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.tokens.create()\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.tokens.create();\n" } ] } }, "/files": { "post": { "tags": [ "Access" ], "summary": "Upload File", "description": "Store a file and return a short-lived URL to pass in a model's `input`.\n\nFree, and available on an empty API wallet \u2014 funding is enforced when you\nsubmit a generation, not when you upload its inputs. `GET /v3/balance`\nreports what the wallet holds.\n\nReturns 402 while uploads are paused, which happens when your recent\nrequests were all refused for insufficient funds. Adding funds to the API\nwallet resumes them.", "operationId": "files_upload", "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "New requests are paused because this user's recent requests were all refused for insufficient funds. Adding funds resumes them.", "content": { "application/json": { "examples": { "unfunded_submit": { "summary": "The API wallet cannot pay for this job", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00 and this request costs $0.05. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "required": 0.05, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } }, "unquotable_submit": { "summary": "The model cannot be priced before its inputs are measured, so `required` is null", "value": { "error": { "code": "INSUFFICIENT_BALANCE", "message": "Your API wallet balance is $0.00. The API wallet is funded separately from Studio and pays only for API requests \u2014 add funds at https://www.hedra.com/develop/billing, then retry.", "retryable": false, "billing": { "balance": 0.0, "currency": "USD", "funding_url": "https://www.hedra.com/develop/billing?add_funds=true" } } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The file to upload." } }, "required": [ "file" ] } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/files\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -F \"file=@/path/to/file\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.files.upload(\n file=\"example_file\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.files.upload({\n file: fs.createReadStream(\"/path/to/your/file\")\n});\n" } ] } }, "/balance": { "get": { "tags": [ "Billing" ], "summary": "Get Balance", "operationId": "billing_get_balance", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/balance\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.billing.get_balance()\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.billing.getBalance();\n" } ] } }, "/usage": { "get": { "tags": [ "Billing" ], "summary": "Get Usage", "operationId": "billing_get_usage", "parameters": [ { "name": "start", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Window start (inclusive, ISO-8601); defaults to 7 days before `end`. Bounds job-creation time.", "title": "Start" }, "description": "Window start (inclusive, ISO-8601); defaults to 7 days before `end`. Bounds job-creation time." }, { "name": "end", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Window end (exclusive, ISO-8601); defaults to now. The window is capped at 90 days.", "title": "End" }, "description": "Window end (exclusive, ISO-8601); defaults to now. The window is capped at 90 days." }, { "name": "group_by", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UsageGroupBy", "description": "One summary row (`total`), one per UTC day (`day`), or one per model (`model`).", "default": "total" }, "description": "One summary row (`total`), one per UTC day (`day`), or one per model (`model`)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/usage\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.billing.get_usage()\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.billing.getUsage();\n" } ] } }, "/transactions": { "get": { "tags": [ "Billing" ], "summary": "List Transactions", "description": "Every movement of the API wallet's balance, newest first: funds added,\njobs charged, charges refunded, and corrections. Scoped to the workspace\nthe credential bills, the same one `GET /v3/balance` reports.", "operationId": "billing_list_transactions", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum items per page.", "default": 20, "title": "Limit" }, "description": "Maximum items per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor from the previous page's `next_cursor`; omit for the first page.", "title": "Cursor" }, "description": "Opaque cursor from the previous page's `next_cursor`; omit for the first page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionListResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/transactions\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.billing.list_transactions()\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.billing.listTransactions();\n" } ] } }, "/webhooks/public-key": { "get": { "tags": [ "Webhooks" ], "summary": "Public Key", "operationId": "webhooks_get_public_key", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPublicKey" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } } } } } }, "security": [], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/webhooks/public-key\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.webhooks.get_public_key()\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.webhooks.getPublicKey();\n" } ] } }, "/webhooks/default": { "get": { "tags": [ "Webhooks" ], "summary": "Get Default", "operationId": "webhooks_get_default", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDefaultConfig" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/webhooks/default\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.webhooks.get_default()\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.webhooks.getDefault();\n" } ] }, "put": { "tags": [ "Webhooks" ], "summary": "Put Default", "operationId": "webhooks_put_default", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDefaultUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDefaultConfig" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X PUT \"https://api.hedra.com/v3/webhooks/default\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"url\"\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.webhooks.put_default(\n url=\"url\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.webhooks.putDefault({\n url: \"url\"\n});\n" } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete Default", "operationId": "webhooks_delete_default", "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X DELETE \"https://api.hedra.com/v3/webhooks/default\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.webhooks.delete_default()\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.webhooks.deleteDefault();\n" } ] } }, "/webhooks/default/test": { "post": { "tags": [ "Webhooks" ], "summary": "Test Default", "operationId": "webhooks_test_default", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/webhooks/default/test\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.webhooks.test_default()\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.webhooks.testDefault();\n" } ] } }, "/webhooks/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List Deliveries", "operationId": "webhooks_list_deliveries", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum items per page.", "default": 20, "title": "Limit" }, "description": "Maximum items per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor from the previous page's `next_cursor`; omit for the first page.", "title": "Cursor" }, "description": "Opaque cursor from the previous page's `next_cursor`; omit for the first page." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryListResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/webhooks/deliveries\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.webhooks.list_deliveries()\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst pageableResponse = await client.webhooks.listDeliveries();\nfor await (const item of pageableResponse) {\n console.log(item);\n}\n\n// Or you can manually iterate page-by-page\nlet page = await client.webhooks.listDeliveries();\nwhile (page.hasNextPage()) {\n page = await page.getNextPage();\n}\n\n// You can also access the underlying response\nconst response = page.response;\n" } ] } }, "/webhooks/deliveries/{job_id}/redeliver": { "post": { "tags": [ "Webhooks" ], "summary": "Redeliver", "description": "Replay a finished delivery: reset it to PENDING and re-fire the signed POST.\n\n404 if the delivery isn't visible to the caller; 409 if a delivery for the\nrequest is still in flight (a replay must not stack on it). The delivery is\nre-validated (SSRF) and re-signed at send time, and the receiver dedupes on\n``X-Hedra-Webhook-Id``, so a replay is safe.\n\nThe webhook id is stable across the original and every replay, because it\nidentifies the event. Every attempt of a replayed cycle therefore also carries\n``X-Hedra-Webhook-Redelivery: true`` \u2014 without it a receiver doing exactly what\nour guidance says (dedupe on the id) would silently discard the replay, which is\nthe one case where the duplicate is the point.", "operationId": "webhooks_redeliver", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The job's id (`job_`).", "title": "Job Id" }, "description": "The job's id (`job_`)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliverySummary" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/webhooks/deliveries/{job_id}/redeliver\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.webhooks.redeliver(\n job_id=\"job_id\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.webhooks.redeliver(\"job_id\");\n" } ] } }, "/log-drains": { "get": { "tags": [ "Log drains" ], "summary": "List Log Drains", "operationId": "log_drains_list_log_drains", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogDrainListResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/log-drains\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.log_drains.list_log_drains()\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.logDrains.listLogDrains();\n" } ] }, "post": { "tags": [ "Log drains" ], "summary": "Create Log Drain", "operationId": "log_drains_create_log_drain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogDrainCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogDrainConfig" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/log-drains\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"name\",\n \"url\": \"url\"\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.log_drains.create_log_drain(\n name=\"name\",\n url=\"url\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.logDrains.createLogDrain({\n name: \"name\",\n url: \"url\"\n});\n" } ] } }, "/log-drains/{drain_id}": { "get": { "tags": [ "Log drains" ], "summary": "Get Log Drain", "operationId": "log_drains_get_log_drain", "parameters": [ { "name": "drain_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The drain's id (`drain_`).", "title": "Drain Id" }, "description": "The drain's id (`drain_`)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogDrainConfig" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl \"https://api.hedra.com/v3/log-drains/{drain_id}\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.log_drains.get_log_drain(\n drain_id=\"drain_id\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.logDrains.getLogDrain(\"drain_id\");\n" } ] }, "patch": { "tags": [ "Log drains" ], "summary": "Update Log Drain", "operationId": "log_drains_update_log_drain", "parameters": [ { "name": "drain_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The drain's id (`drain_`).", "title": "Drain Id" }, "description": "The drain's id (`drain_`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogDrainUpdate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogDrainConfig" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X PATCH \"https://api.hedra.com/v3/log-drains/{drain_id}\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"name\",\n \"url\": \"url\",\n \"format\": \"ndjson\",\n \"secret\": \"secret\",\n \"headers\": null,\n \"enabled\": true,\n \"batch_size\": 1.0\n}'\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.log_drains.update_log_drain(\n drain_id=\"drain_id\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.logDrains.updateLogDrain(\"drain_id\");\n" } ] }, "delete": { "tags": [ "Log drains" ], "summary": "Delete Log Drain", "operationId": "log_drains_delete_log_drain", "parameters": [ { "name": "drain_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The drain's id (`drain_`).", "title": "Drain Id" }, "description": "The drain's id (`drain_`)." } ], "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X DELETE \"https://api.hedra.com/v3/log-drains/{drain_id}\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.log_drains.delete_log_drain(\n drain_id=\"drain_id\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.logDrains.deleteLogDrain(\"drain_id\");\n" } ] } }, "/log-drains/{drain_id}/test": { "post": { "tags": [ "Log drains" ], "summary": "Test Log Drain", "operationId": "log_drains_test_log_drain", "parameters": [ { "name": "drain_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The drain's id (`drain_`).", "title": "Drain Id" }, "description": "The drain's id (`drain_`)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogDrainTestResponse" } } } }, "400": { "description": "Invalid or failed-validation request.", "content": { "application/json": { "examples": { "field_validation": { "summary": "A submit `input` field failed schema validation", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "2 input fields are invalid; see details.", "retryable": false, "param": "input.aspect_ratio", "details": [ { "field": "input.aspect_ratio", "message": "input.aspect_ratio: Input should be '16:9', '9:16' or '1:1'", "reason": "enum" }, { "field": "input.duration_ms", "message": "input.duration_ms: Input should be greater than or equal to 1000", "reason": "minimum" } ] } } }, "expired_file_handle": { "summary": "A `POST /v3/files` handle was submitted past its `expires_at`", "value": { "error": { "code": "INVALID_ARGUMENT", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "retryable": false, "param": "input.images[0]", "details": [ { "field": "input.images[0]", "message": "input.images[0]: the POST /v3/files url expired at 2026-07-28T23:31:12+00:00. Upload the file again and submit with the fresh url.", "reason": "expired" } ] } } }, "unsupported_model": { "summary": "The model exists but isn't wired to v3 yet", "value": { "error": { "code": "FAILED_PRECONDITION", "message": "Model 'some-model' (VIDEO_STITCHING) is not supported on v3 yet.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Insufficient scope or plan.", "content": { "application/json": { "examples": { "no_workspace_access": { "summary": "Key no longer reaches its workspace", "value": { "error": { "code": "PERMISSION_DENIED", "message": "The key's owner is no longer a member of its workspace.", "retryable": false } } }, "missing_scope": { "summary": "Key lacks a scope the operation requires", "value": { "error": { "code": "PERMISSION_DENIED", "message": "Key is missing required scope(s): jobs:write.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "examples": { "job_not_found": { "summary": "Unknown job id, or not visible to the caller", "value": { "error": { "code": "NOT_FOUND", "message": "Job not found.", "retryable": false } } }, "model_not_found": { "summary": "No such model in the catalog", "value": { "error": { "code": "NOT_FOUND", "message": "Model 'some-model' not found.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Request budget for the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix epoch second the window resets at.", "schema": { "type": "integer" } } }, "content": { "application/json": { "examples": { "rate_limited": { "summary": "Per-key request rate limit exceeded", "value": { "error": { "code": "RESOURCE_EXHAUSTED", "message": "Request rate limit exceeded: this API key is limited to 60 requests per 60s. Retry after 30s. To follow job progress without polling, stream job status (https://www.hedra.com/docs/api-reference/v3/jobs/stream-job) or subscribe to webhooks (https://www.hedra.com/docs/api-reference/v3/webhooks).", "retryable": true, "retry_after": 30 } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "examples": { "internal": { "summary": "Unexpected server error; internals are never leaked", "value": { "error": { "code": "INTERNAL", "message": "An unexpected error occurred", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed: missing, malformed, or invalid credentials.", "content": { "application/json": { "examples": { "missing_credentials": { "summary": "No credential on the request", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing credentials. Send 'Authorization: Key :' or 'Authorization: Bearer '.", "retryable": false } } }, "invalid_key": { "summary": "Credential present but not valid", "value": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "KeyAuth": [] }, { "BearerToken": [] } ], "x-codeSamples": [ { "lang": "bash", "label": "cURL", "source": "curl -X POST \"https://api.hedra.com/v3/log-drains/{drain_id}/test\" \\\n -H \"Authorization: Bearer $HEDRA_API_KEY\"\n" }, { "lang": "python", "label": "hedra-python", "source": "from hedra import Hedra\n\nclient = Hedra(api_key=\"YOUR_API_KEY\")\n\nclient.log_drains.test_log_drain(\n drain_id=\"drain_id\",\n)\n" }, { "lang": "typescript", "label": "hedra-node", "source": "import { HedraClient } from \"hedra-node\";\n\nconst client = new HedraClient({ apiKey: \"YOUR_API_KEY\" });\n\nawait client.logDrains.testLogDrain(\"drain_id\");\n" } ] } } }, "components": { "schemas": { "ApiKeyKind": { "type": "string", "enum": [ "personal", "service" ], "title": "ApiKeyKind", "description": "Personal keys die with the member; service keys belong to the workspace." }, "ApiKeyScope": { "type": "string", "enum": [ "jobs:read", "jobs:write", "models:read", "files:write", "webhooks:manage", "log_drains:manage", "usage:read", "keys:manage", "chat:write" ], "title": "ApiKeyScope", "description": "Least-privilege grants carried by v3 API keys.\n\nStored as text[] on api_keys; NULL scopes means full access (legacy keys).\nScopes are stored as text so new least-privilege surfaces can be introduced\nwithout a database-enum migration." }, "BalanceResponse": { "properties": { "balance": { "type": "number", "title": "Balance", "description": "Spendable balance." }, "spent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Spent", "description": "Amount consumed in the current billing period; null for the non-expiring API wallet (see GET /v3/usage)." }, "currency": { "type": "string", "title": "Currency", "description": "ISO-4217 currency code for every amount in this response." } }, "type": "object", "required": [ "balance", "currency" ], "title": "BalanceResponse", "description": "Spendable balance on the account this key bills.\n\nSourced from the workspace wallet for a workspace-bound key, else the\ncaller's personal balance. While the segregated API wallet is enabled, both\nkey types instead read the API wallet that generation debits draw on (a\npersonal key resolves its bound workspace).\n\nEvery amount is in US dollars." }, "BillingError": { "properties": { "balance": { "type": "number", "title": "Balance", "description": "Spendable balance on the account this request bills, at the moment it was refused. The same value `GET /balance` returns." }, "required": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Required", "description": "What this request needed. Null when the refusal is a funding precondition rather than a priced one \u2014 an upload is not priced, and some models cannot be quoted until their inputs are measured (`POST /models/{model}/estimate` says so explicitly)." }, "currency": { "type": "string", "title": "Currency", "description": "ISO-4217 code the amounts above are denominated in.", "default": "USD" }, "funding_url": { "type": "string", "title": "Funding Url", "description": "Where a human can add funds to the account this request bills. The API itself cannot add them." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Why the automatic top-up did not fund the balance, when known. `card_declined`: the card that pays for automatic top-ups was declined, and the payment method must be updated on the billing page before a top-up can succeed. Clients MUST tolerate unrecognized values: new reasons may be added at any time." } }, "type": "object", "required": [ "balance", "funding_url" ], "title": "BillingError", "description": "Why a request was refused for funds, and what would clear it.\n\nThe envelope's structured detail for `INSUFFICIENT_BALANCE`, the way\n`details` is its structured detail for a validation failure. Every amount is\nin `currency`, and `balance` is the same number `GET /balance` returns \u2014 so\na client can decide whether to top up, wait, or fail over without a second\nround trip to work out which balance was short." }, "ErrorCode": { "type": "string", "enum": [ "UNKNOWN", "INVALID_ARGUMENT", "NOT_FOUND", "GONE", "ALREADY_EXISTS", "ALREADY_IN_PROGRESS", "UNAUTHORIZED", "PERMISSION_DENIED", "INSUFFICIENT_BALANCE", "MODERATION_FAILED", "FAILED_PRECONDITION", "CANCELLED", "DEADLINE_EXCEEDED", "RESOURCE_EXHAUSTED", "UNAVAILABLE", "INTERNAL" ], "title": "ErrorCode", "description": "Universal error code space. Modeled after gRPC status codes.\n\nEvery exception in the system carries an ErrorCode. SDK clients map\n3rd-party errors to these codes at the lowest level. Retry logic,\nHTTP status mapping, and OTEL metrics all key off this enum.\n\nNOTE: The semantic meaning of these error codes is roughly mapped from the\n semantic of the gRPC status codes: see\n https://grpc.io/docs/guides/status-codes/ for details." }, "ErrorEnvelope": { "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string", "title": "Message", "description": "Human-readable summary of the error. Fixed per condition \u2014 match on `code`, not on this text." }, "retryable": { "type": "boolean", "title": "Retryable", "description": "Whether retrying the same request can succeed. Describes the condition, not a promise \u2014 pair with `retry_after` when present.", "default": false }, "retry_after": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Retry After", "description": "Seconds to wait before retrying; set when the error is retryable. Mirrors the `Retry-After` response header." }, "param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Param", "description": "The primary offending input field, when the error is about one specific field." }, "details": { "anyOf": [ { "items": { "$ref": "#/components/schemas/FieldError" }, "type": "array" }, { "type": "null" } ], "title": "Details", "description": "Every field-level problem, when the error is a validation failure \u2014 all of them at once, not just the first." }, "replaced_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Replaced By", "description": "The id of a successor model, set when the requested model has been retired (code `GONE`) and replaced; null otherwise. Lets a client programmatically migrate off a retired model." }, "billing": { "anyOf": [ { "$ref": "#/components/schemas/BillingError" }, { "type": "null" } ], "description": "Balance, price, and where to add funds \u2014 set when the request was refused for funds (code `INSUFFICIENT_BALANCE`); null otherwise." } }, "type": "object", "required": [ "code", "message" ], "title": "ErrorEnvelope" }, "ErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id", "description": "Debug id to quote to support (32-char hex trace id), also emitted as the `X-Trace-Id` response header." } }, "type": "object", "required": [ "error" ], "title": "ErrorResponse", "description": "Top-level error body: ``{\"error\": {...}}`` plus a debug id." }, "EstimateRequest": { "properties": { "input": { "additionalProperties": true, "type": "object", "title": "Input", "description": "The same model-specific inputs a submit would carry; the estimate prices exactly this body." } }, "type": "object", "title": "EstimateRequest" }, "EstimateResponse": { "properties": { "model": { "type": "string", "title": "Model", "description": "The resolved model id this estimate prices." }, "cost": { "type": "number", "title": "Cost", "description": "Price of a would-be submit." }, "currency": { "type": "string", "title": "Currency", "description": "ISO-4217 currency code for `cost`." } }, "type": "object", "required": [ "model", "cost", "currency" ], "title": "EstimateResponse", "description": "Price of a would-be submit, in US dollars." }, "FieldError": { "properties": { "field": { "type": "string", "title": "Field", "description": "Dotted path to the offending input (e.g. `input.resolution`)." }, "message": { "type": "string", "title": "Message", "description": "What is wrong with this field's value." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Machine-readable hint for which constraint failed (\"required\", \"enum\", \"type\", \u2026)." }, "allowed": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed", "description": "Accepted values for an enum, or accepted field names on the first unknown-field violation. Omitted on subsequent unknown fields." } }, "type": "object", "required": [ "field", "message" ], "title": "FieldError", "description": "One field-level validation problem in a request body.\n\n`field` is the dotted path to the offending input (e.g. `input.resolution`);\n`allowed` lists the accepted values when the field is an enum, so a caller\ncan fix it without re-fetching the model schema." }, "FileUploadResponse": { "properties": { "url": { "type": "string", "title": "Url", "description": "Presigned GET URL for the stored bytes \u2014 the handle itself. Pass it back verbatim, query string included: a modified URL is not recognised as your handle and is rejected as an external URL." }, "content_type": { "type": "string", "title": "Content Type", "description": "MIME type sniffed from the uploaded bytes; the request's own Content-Type and filename are never trusted. Decides which media inputs will accept this handle." }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At", "description": "ISO-8601 instant `url` stops being accepted \u2014 one hour after upload. Submitting with a lapsed handle is a 400 with `reason: \"expired\"`, not a fetch failure; upload the file again for a fresh handle. The stored object is deleted separately by a bucket lifecycle policy about a day after upload, so treat re-uploading, not re-presigning, as the remedy." } }, "type": "object", "required": [ "url", "content_type", "expires_at" ], "title": "FileUploadResponse", "description": "``POST /v3/files`` result. The presigned ``url`` *is* the file handle:\npass it as ``{\"source\": \"url\", \"url\": }`` in any media input the\nmodel's schema advertises (``image`` / ``end_image`` / ``images`` /\n``audio`` / ``video``) on submit." }, "JobListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/JobSummary" }, "type": "array", "title": "Data", "description": "This page of items." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque cursor for the next page, or null when this response completes the list. Always present. Endpoints that serve the whole collection at once always return null." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "JobListResponse" }, "JobLogEvent": { "type": "string", "enum": [ "queued", "started", "moderation.passed", "provider.submitted", "provider.error", "retry.scheduled", "progress", "finalizing", "download.ready", "completed", "failed", "recovered" ], "title": "JobLogEvent" }, "JobLogItem": { "properties": { "id": { "type": "integer", "title": "Id", "description": "Monotonically increasing id of this event within the job's log. Cursors are separate opaque values (`next_cursor` / `logs_next_cursor`); do not send this id as one." }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "ISO-8601 instant the event was recorded." }, "level": { "$ref": "#/components/schemas/JobLogLevel" }, "event": { "$ref": "#/components/schemas/JobLogEvent" }, "message": { "type": "string", "title": "Message", "description": "Human-readable summary of the event." }, "source": { "$ref": "#/components/schemas/JobLogSource" }, "data": { "additionalProperties": true, "type": "object", "title": "Data", "description": "Structured detail specific to this event type; empty when the event carries none." } }, "type": "object", "required": [ "id", "timestamp", "level", "event", "message", "source" ], "title": "JobLogItem", "description": "One customer-visible lifecycle event for a v3 job." }, "JobLogLevel": { "type": "string", "enum": [ "info", "warning", "error" ], "title": "JobLogLevel" }, "JobLogListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/JobLogItem" }, "type": "array", "title": "Data", "description": "This page of items." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque cursor for the next page, or null when this response completes the list. Always present. Endpoints that serve the whole collection at once always return null." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "JobLogListResponse" }, "JobLogSource": { "type": "string", "enum": [ "api", "worker", "provider", "cron" ], "title": "JobLogSource" }, "JobStatus": { "type": "string", "enum": [ "IN_QUEUE", "IN_PROGRESS", "COMPLETED", "FAILED" ], "title": "JobStatus", "description": "The four states a job can be in." }, "JobSummary": { "properties": { "job_id": { "type": "string", "title": "Job Id", "description": "The job's id \u2014 server-issued, and opaque." }, "model": { "type": "string", "title": "Model", "description": "The resolved model id this job ran on." }, "quality": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quality", "description": "The quality level this job ran at; present only for models that offer quality levels." }, "status": { "$ref": "#/components/schemas/JobStatus" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "ISO-8601 instant the job was submitted." } }, "type": "object", "required": [ "job_id", "model", "status", "created_at" ], "title": "JobSummary" }, "KeyCreateRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable label for the key." }, "scopes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ApiKeyScope" }, "type": "array" }, { "type": "null" } ], "title": "Scopes", "description": "Scopes granted to the key; omitted means full access." }, "kind": { "$ref": "#/components/schemas/ApiKeyKind", "description": "`personal` (default) dies with the member; `service` is workspace-shared, OWNER/ADMIN-managed, and survives member removal.", "default": "personal" }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id", "description": "Target workspace; omitted means the authenticating key's workspace." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "ISO-8601 instant the key stops authenticating; omitted means it never expires." } }, "type": "object", "title": "KeyCreateRequest" }, "KeyCreateResponse": { "properties": { "key_id": { "type": "string", "title": "Key Id", "description": "The key's public identifier." }, "credential": { "type": "string", "title": "Credential", "description": "The full `:` pair \u2014 a valid Bearer credential. Returned exactly once, at creation; store it now." }, "kind": { "$ref": "#/components/schemas/ApiKeyKind" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable label for the key." }, "scopes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Scopes", "description": "Scopes granted to the key; null means full access (a legacy key predating scopes)." }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id", "description": "The workspace the key bills and acts in." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "ISO-8601 instant the key stops authenticating; null means it never expires." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "ISO-8601 instant the key was created." } }, "type": "object", "required": [ "key_id", "credential", "kind" ], "title": "KeyCreateResponse" }, "KeyListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/KeySummary" }, "type": "array", "title": "Data", "description": "This page of items." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque cursor for the next page, or null when this response completes the list. Always present. Endpoints that serve the whole collection at once always return null." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "KeyListResponse" }, "KeyRotateRequest": { "properties": { "grace_period_seconds": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Grace Period Seconds", "description": "Seconds the old secret keeps authenticating after the rotation; omitted means the service default (24h)." } }, "type": "object", "title": "KeyRotateRequest" }, "KeyRotateResponse": { "properties": { "key_id": { "type": "string", "title": "Key Id", "description": "The key's public identifier \u2014 unchanged by rotation." }, "credential": { "type": "string", "title": "Credential", "description": "The new `:` pair \u2014 a valid Bearer credential, shown exactly once, like at create." }, "kind": { "$ref": "#/components/schemas/ApiKeyKind" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable label for the key." }, "scopes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Scopes", "description": "Scopes granted to the key; null means full access (a legacy key predating scopes)." }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id", "description": "The workspace the key bills and acts in." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "ISO-8601 instant the key stops authenticating; null means it never expires." }, "previous_secret_expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Previous Secret Expires At", "description": "ISO-8601 instant the previous secret stops authenticating \u2014 the end of the grace window." } }, "type": "object", "required": [ "key_id", "credential", "kind" ], "title": "KeyRotateResponse" }, "KeyStatus": { "type": "string", "enum": [ "active", "revoked", "expired" ], "title": "KeyStatus" }, "KeySummary": { "properties": { "key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Key Id", "description": "The key's public identifier; null only for legacy rows predating public key ids." }, "kind": { "$ref": "#/components/schemas/ApiKeyKind" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable label for the key." }, "scopes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Scopes", "description": "Scopes granted to the key; null means full access (a legacy key predating scopes)." }, "workspace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Id", "description": "The workspace the key bills and acts in." }, "status": { "$ref": "#/components/schemas/KeyStatus" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "ISO-8601 instant the key was created." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "ISO-8601 instant the key stops authenticating; null means it never expires." }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Revoked At", "description": "ISO-8601 instant the key was revoked; null unless `status` is `revoked`." }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Used At", "description": "ISO-8601 instant the key last authenticated a request; null when unused." } }, "type": "object", "required": [ "key_id", "kind", "status" ], "title": "KeySummary" }, "LogDrainConfig": { "properties": { "id": { "type": "string", "title": "Id", "description": "The drain's id (`drain_`)." }, "name": { "type": "string", "title": "Name", "description": "Human-readable label." }, "url": { "type": "string", "title": "Url", "description": "The destination endpoint." }, "format": { "$ref": "#/components/schemas/LogDrainFormat" }, "header_names": { "items": { "type": "string" }, "type": "array", "title": "Header Names", "description": "Names of the configured extra headers. Values are write-only and never echoed back." }, "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether the drain receives batches." }, "batch_size": { "type": "integer", "title": "Batch Size", "description": "Maximum log lines per post." }, "consecutive_failures": { "type": "integer", "title": "Consecutive Failures", "description": "Failed batches since the last success; the drain auto-disables when it crosses the failure threshold." }, "last_success_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Success At", "description": "ISO-8601 instant of the last delivered batch." }, "last_failure_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Failure At", "description": "ISO-8601 instant of the last failed batch." }, "last_failure_status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Last Failure Status", "description": "HTTP status of the last failed batch; null when it never got a response." }, "last_error": { "anyOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "type": "null" } ], "description": "Why the most recent batch delivery failed, in the same error envelope `GET /jobs/{job_id}` returns for a failed job: a stable `code` from the shared error vocabulary, a fixed operator-facing `message`, and `retryable`. Null while no batch has failed, and cleared on the next success. Destination URLs, headers, credentials, response bodies, and internal exception text are never included. Nor is your drain URL written to Hedra's own logs, since it may carry authentication in its query string. `retryable` describes the condition, not what Hedra did: every failed batch is requeued until the drain auto-disables, so it answers whether fixing the destination and re-enabling is likely to help. Drains that last failed before this field became structured report `UNKNOWN`." }, "disabled_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Disabled Reason", "description": "Why the drain is off (`consecutive_failures` for auto-disable, `disabled_by_user`); null while enabled." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "ISO-8601 instant the drain was created." }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "ISO-8601 instant the config last changed." }, "updated_by_key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated By Key Id", "description": "The API key that last changed the config." } }, "type": "object", "required": [ "id", "name", "url", "format", "enabled", "batch_size", "consecutive_failures", "created_at", "updated_at" ], "title": "LogDrainConfig" }, "LogDrainCreate": { "allOf": [ { "if": { "properties": { "format": { "enum": [ "ndjson" ] } } }, "then": { "properties": { "secret": { "type": "string" } }, "required": [ "secret" ] } } ], "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name", "description": "Human-readable label." }, "url": { "type": "string", "maxLength": 8192, "minLength": 1, "title": "Url", "description": "HTTPS endpoint job-log batches are posted to." }, "format": { "$ref": "#/components/schemas/LogDrainFormat", "default": "ndjson" }, "secret": { "anyOf": [ { "type": "string", "maxLength": 4096, "minLength": 64, "format": "password", "writeOnly": true }, { "type": "null" } ], "title": "Secret", "description": "Signs every NDJSON post. Required when `format` is `ndjson` (the default); optional for `otlp` drains, whose receivers authenticate with `headers` instead.", "writeOnly": true }, "headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Headers", "description": "Extra headers sent with every post \u2014 typically the receiver's authentication. Stored values are never echoed back; reads expose `header_names` only.", "writeOnly": true }, "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether the drain receives batches.", "default": true }, "batch_size": { "type": "integer", "maximum": 5000.0, "minimum": 1.0, "title": "Batch Size", "description": "Maximum log lines per post.", "default": 1000 } }, "type": "object", "required": [ "name", "url" ], "title": "LogDrainCreate" }, "LogDrainFormat": { "type": "string", "enum": [ "ndjson", "otlp" ], "title": "LogDrainFormat", "description": "Wire encoding for one log drain endpoint's HTTP posts." }, "LogDrainListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/LogDrainConfig" }, "type": "array", "title": "Data", "description": "This page of items." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque cursor for the next page, or null when this response completes the list. Always present. Endpoints that serve the whole collection at once always return null." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "LogDrainListResponse" }, "LogDrainTestResponse": { "properties": { "ok": { "type": "boolean", "title": "Ok", "description": "Whether the test batch got a 2xx from the endpoint." }, "response_status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Response Status", "description": "HTTP status the endpoint returned; null when the request never got a response." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Why the test failed; null on success." } }, "type": "object", "required": [ "ok" ], "title": "LogDrainTestResponse" }, "LogDrainUpdate": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 100, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "New label; omitted means unchanged." }, "url": { "anyOf": [ { "type": "string", "maxLength": 8192, "minLength": 1 }, { "type": "null" } ], "title": "Url", "description": "New destination; omitted means unchanged." }, "format": { "anyOf": [ { "$ref": "#/components/schemas/LogDrainFormat" }, { "type": "null" } ], "description": "New wire format; omitted means unchanged." }, "secret": { "anyOf": [ { "type": "string", "maxLength": 4096, "minLength": 64, "format": "password", "writeOnly": true }, { "type": "null" } ], "title": "Secret", "description": "Rotates the signing secret. No conditional applies here: the drain may already hold one. Switching `format` to `ndjson` on a drain with no stored secret requires supplying one in the same request.", "writeOnly": true }, "headers": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Headers", "description": "Replaces the full header set; `{}` clears it. Omitted means unchanged.", "writeOnly": true }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enabled", "description": "Pause (false) or resume (true) the drain; omitted means unchanged. Re-enabling clears the auto-disable failure count." }, "batch_size": { "anyOf": [ { "type": "integer", "maximum": 5000.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Batch Size", "description": "New maximum log lines per post; omitted means unchanged." } }, "type": "object", "title": "LogDrainUpdate" }, "Metrics": { "properties": { "processing_time_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Processing Time Ms", "description": "Wall-clock milliseconds between this job's `started` and `completed` lifecycle events. It brackets provider queueing, generation, output download, and any failed attempts with their retry backoff, so it measures the whole job rather than the model's own inference time, and it is not a provider-reported figure. Read from the job's durable lifecycle records, so polled results and webhook deliveries report the same value. Null when the job did not record both events." } }, "type": "object", "title": "Metrics", "description": "Timing measured for a completed job." }, "Modality": { "type": "string", "enum": [ "image", "video", "audio" ], "title": "Modality", "description": "The kind of output a model produces \u2014 the axis `?modality=` filters on." }, "ModelDetail": { "properties": { "id": { "type": "string", "title": "Id", "description": "The model's public id \u2014 the value POST /v3/models/{model} takes." }, "modality": { "$ref": "#/components/schemas/Modality" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "One-line summary of what the model does." }, "price_description": { "type": "string", "title": "Price Description", "description": "Short USD pricing summary for this model. Exact cost depends on input.", "default": "Price varies by generation settings." }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Url", "description": "URL of the provider's logo." }, "input_schema": { "additionalProperties": true, "type": "object", "title": "Input Schema", "description": "JSON Schema for this model's `input` object on submit \u2014 the same schema `GET /v3/models/{model}/openapi.json` embeds." }, "output_schema": { "additionalProperties": true, "type": "object", "title": "Output Schema", "description": "JSON Schema of one item of a completed job's `outputs[]`." } }, "type": "object", "required": [ "id", "modality" ], "title": "ModelDetail" }, "ModelListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ModelSummary" }, "type": "array", "title": "Data", "description": "This page of items." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque cursor for the next page, or null when this response completes the list. Always present. Endpoints that serve the whole collection at once always return null." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "ModelListResponse" }, "ModelSummary": { "properties": { "id": { "type": "string", "title": "Id", "description": "The model's public id \u2014 the value POST /v3/models/{model} takes." }, "modality": { "$ref": "#/components/schemas/Modality" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable name." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "One-line summary of what the model does." }, "price_description": { "type": "string", "title": "Price Description", "description": "Short USD pricing summary for this model. Exact cost depends on input.", "default": "Price varies by generation settings." }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Url", "description": "URL of the provider's logo." } }, "type": "object", "required": [ "id", "modality" ], "title": "ModelSummary" }, "OutputItem": { "properties": { "status": { "$ref": "#/components/schemas/OutputStatus", "default": "COMPLETED" }, "asset_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Asset Id", "description": "This output's asset id \u2014 server-issued, and opaque. Pass it as `{\"source\": \"asset\", \"asset_id\": ...}` in a later submit's media inputs to reuse this output as a reference. Null once the output has expired, since its bytes are no longer retrievable." }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id", "description": "The voice a voice-clone job created (`voice_`). Send it back as `voice_id` on a text-to-speech submit to speak with this voice; it stays usable by the account that created it. Null for every other kind of output." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "uri", "title": "Url", "description": "Presigned download URL for the output bytes. Null once the output has expired." }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content Type", "description": "MIME type of the output bytes." }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width", "description": "Width in pixels; null for an output with no frame (audio)." }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height", "description": "Height in pixels; null for an output with no frame (audio)." }, "duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Ms", "description": "Duration in milliseconds; null for a still image." }, "fps": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Fps", "description": "The video's measured frame rate; null for a non-video output and for a video that has not been probed yet." }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "type": "null" } ], "description": "Why this item failed \u2014 present on a failed item within an otherwise-completed batch." } }, "type": "object", "title": "OutputItem", "description": "One item of a job's `outputs[]` (`GET /v3/jobs/{job_id}`). `outputs` is\nalways an array, even for a single output.\n\nEvery key is always present. The ones a modality carries no value for\nserialize as null \u2014 an image output reports `duration_ms: null` and\n`fps: null`, an audio output `width: null` \u2014 so the shape is one object\nrather than one per modality. `url` and `asset_id` go null on an expired\noutput, which has metadata but no retrievable bytes.\n\nA voice-clone job's output is a voice rather than a file: it reports\n`voice_id` and leaves `url`, `content_type`, and `asset_id` null, since\nthere are no bytes to fetch and nothing to pass back as a media input." }, "OutputStatus": { "type": "string", "enum": [ "COMPLETED", "FAILED", "EXPIRED" ], "title": "OutputStatus", "description": "The state of a single output within a job's result." }, "ResultResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id", "description": "The job this envelope describes." }, "model": { "type": "string", "title": "Model", "description": "The resolved model id this job ran on." }, "quality": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quality", "description": "The quality level this job ran at; present only for models that offer quality levels." }, "status": { "$ref": "#/components/schemas/JobStatus" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt", "description": "The prompt this job ran with. When `enhance_prompt` was set, this is the rewritten prompt the model received rather than the one submitted. Absent on models that take no prompt." }, "outputs": { "items": { "$ref": "#/components/schemas/OutputItem" }, "type": "array", "title": "Outputs", "description": "The job's outputs \u2014 always an array, even for a single output; empty until the job completes." }, "metrics": { "anyOf": [ { "$ref": "#/components/schemas/Metrics" }, { "type": "null" } ], "description": "Timing for this job; present on completed jobs only." }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "type": "null" } ], "description": "Why the job failed; null unless `status` is `FAILED`." }, "logs": { "anyOf": [ { "items": { "$ref": "#/components/schemas/JobLogItem" }, "type": "array" }, { "type": "null" } ], "title": "Logs", "description": "The most recent lifecycle events for this job, oldest first. Capped; GET /v3/jobs/{job_id}/logs serves the full paginated history. Absent from webhook payloads." }, "cost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cost", "description": "Net cost of this job; 0 when fully refunded; absent until charged. Absent from webhook payloads." }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currency", "description": "ISO-4217 currency code for `cost`. Present exactly when `cost` is." } }, "type": "object", "required": [ "job_id", "model", "status" ], "title": "ResultResponse" }, "StatusResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id", "description": "The job this status describes." }, "status": { "$ref": "#/components/schemas/JobStatus" }, "progress": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "maximum": 1.0, "minimum": 0.0, "title": "Progress", "description": "Fraction of the job completed, from 0 to 1 (not a percentage). Null when the job has not reported progress yet." }, "estimated_completion_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Estimated Completion At", "description": "ISO-8601 instant this job is estimated to finish; null when no estimate exists for the model yet. Refreshed on every poll." }, "logs": { "anyOf": [ { "items": { "$ref": "#/components/schemas/JobLogItem" }, "type": "array" }, { "type": "null" } ], "title": "Logs", "description": "Lifecycle events newer than the `logs_after` cursor, oldest first. Present only when `logs_after` is supplied; absent from SSE status frames and MCP progress notifications." }, "logs_next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logs Next Cursor", "description": "Cursor to send as `logs_after` on the next poll. Absent when this poll delivered no new events \u2014 keep using the cursor you sent." } }, "type": "object", "required": [ "job_id", "status" ], "title": "StatusResponse", "description": "The lightweight poll envelope, also the SSE ``status`` frame and the MCP\nprogress notification payload.\n\nThe two log fields are poll-only by construction, like ``cost`` on\nthe result envelope: they are populated when \u2014 and only when \u2014 a\n``GET /v3/jobs/{job_id}/status`` caller supplies a ``logs_after`` cursor, and\nthey exclude when ``None``, so the frame the stream transports build from a\nRedis payload with no DB session is byte-identical to a log-free envelope.\nThat was ENG-9693's reason for having no ``logs`` field at all; the stream\nnow carries lifecycle rows as their own ``event: log`` frames instead of\ninside this one (ENG-9694)." }, "TokenCreateRequest": { "properties": { "ttl_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Ttl Seconds", "description": "Seconds until the token expires; omitted means the service default." }, "scopes": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ApiKeyScope" }, "type": "array" }, { "type": "null" } ], "title": "Scopes", "description": "Scopes granted to the token. Omitted means every scope of the minting key; an explicit subset narrows the grant, and requesting beyond the key's scopes is a 403." } }, "type": "object", "title": "TokenCreateRequest" }, "TokenCreateResponse": { "properties": { "token": { "type": "string", "title": "Token", "description": "The ephemeral token \u2014 a valid Bearer credential until it expires. Shown exactly once." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "ISO-8601 instant the token stops authenticating." } }, "type": "object", "required": [ "token" ], "title": "TokenCreateResponse" }, "TransactionListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/TransactionRecord" }, "type": "array", "title": "Data", "description": "This page of items." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque cursor for the next page, or null when this response completes the list. Always present. Endpoints that serve the whole collection at once always return null." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "TransactionListResponse" }, "TransactionRecord": { "properties": { "id": { "type": "string", "title": "Id", "description": "The transaction's id. Stable, and the same id the V2 billing history reports for this row." }, "kind": { "type": "string", "title": "Kind", "description": "What moved the balance: `purchase` when funds were bought, `grant` when they were granted by a plan entitlement, `usage` when a job was charged, `refund` when a charge was returned, `adjustment` when Hedra corrected the balance, and `other` for a movement this API version does not yet name. The list is open and may gain values, so switch on it with a default branch; `amount` is authoritative for a kind you do not recognize." }, "amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Amount", "description": "The change to the balance, signed: negative for a charge, positive for funds arriving. Null for a row written before the wallet recorded amounts, whose movement is unknown rather than zero; no such row exists in production." }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currency", "description": "ISO-4217 currency code for `amount`; null exactly when `amount` is." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "ISO-8601 instant the balance moved." } }, "type": "object", "required": [ "id", "kind", "amount", "currency", "created_at" ], "title": "TransactionRecord", "description": "One movement of the API wallet's balance." }, "UsageBucket": { "properties": { "key": { "type": "string", "title": "Key", "description": "What this bucket rolls up: `\"total\"`, an ISO date (`YYYY-MM-DD`, UTC), or a public model id \u2014 per `group_by`." }, "jobs": { "type": "integer", "title": "Jobs", "description": "Jobs submitted in this bucket." }, "requests": { "type": "integer", "title": "Requests", "description": "Settled LLM chat requests in this bucket. Unlike `jobs` (which counts submits, charged or not), this counts requests whose usage settled \u2014 a request refused before any work never appears, and a late settlement lands in the window the request was created in.", "default": 0 }, "spent": { "type": "number", "title": "Spent", "description": "Net amount spent in this bucket." } }, "type": "object", "required": [ "key", "jobs", "spent" ], "title": "UsageBucket", "description": "One usage rollup row. `key` is ``\"total\"`` for the summary, an ISO date\n(``YYYY-MM-DD``, UTC) for ``group_by=day``, or a public model id for\n``group_by=model``." }, "UsageGroupBy": { "type": "string", "enum": [ "total", "day", "model" ], "title": "UsageGroupBy" }, "UsageResponse": { "properties": { "start": { "type": "string", "format": "date-time", "title": "Start", "description": "Window start (inclusive)." }, "end": { "type": "string", "format": "date-time", "title": "End", "description": "Window end (exclusive)." }, "group_by": { "$ref": "#/components/schemas/UsageGroupBy" }, "total_jobs": { "type": "integer", "title": "Total Jobs", "description": "Jobs submitted across the whole window." }, "total_requests": { "type": "integer", "title": "Total Requests", "description": "Settled LLM chat requests across the whole window.", "default": 0 }, "total_spent": { "type": "number", "title": "Total Spent", "description": "Net amount spent across the whole window." }, "currency": { "type": "string", "title": "Currency", "description": "ISO-4217 currency code for every amount in this response." }, "data": { "items": { "$ref": "#/components/schemas/UsageBucket" }, "type": "array", "title": "Data", "description": "One bucket per `group_by` group." } }, "type": "object", "required": [ "start", "end", "group_by", "total_jobs", "total_spent", "currency" ], "title": "UsageResponse" }, "VoiceGender": { "type": "string", "enum": [ "male", "female" ], "title": "VoiceGender", "description": "The `gender` curation label, as a voice search filter.\n\nTwo members because the label carries exactly two values across every\nprovider; published as an enum so a generated SDK types the filter rather\nthan taking any string and failing at the boundary." }, "VoiceListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/VoiceSummary" }, "type": "array", "title": "Data", "description": "This page of items." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque cursor for the next page, or null when this response completes the list. Always present. Endpoints that serve the whole collection at once always return null." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "VoiceListResponse" }, "VoiceSummary": { "properties": { "id": { "type": "string", "title": "Id", "description": "The voice's id (`voice_`); pass it as `input.voice_id` on submit." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Human-readable name." }, "preview_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Preview Url", "description": "URL of a short audio sample of this voice." }, "labels": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Labels", "description": "Curation metadata (language, gender, accent, ...)." } }, "type": "object", "required": [ "id" ], "title": "VoiceSummary", "description": "One voice a model accepts; `id` goes into ``input.voice_id`` on submit." }, "WebhookDefaultConfig": { "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "The stored default endpoint; null when none is configured." }, "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether the default endpoint is active.", "default": false }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "ISO-8601 instant the config last changed." }, "updated_by_key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated By Key Id", "description": "The API key that last changed the config." } }, "type": "object", "title": "WebhookDefaultConfig" }, "WebhookDefaultUpdate": { "properties": { "url": { "type": "string", "maxLength": 8192, "minLength": 1, "title": "Url", "description": "HTTPS endpoint to receive terminal webhooks for every job that names no per-job `webhook` on submit." }, "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether the default endpoint receives deliveries; false pauses it without discarding the URL.", "default": true } }, "type": "object", "required": [ "url" ], "title": "WebhookDefaultUpdate" }, "WebhookDeliveryListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookDeliverySummary" }, "type": "array", "title": "Data", "description": "This page of items." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque cursor for the next page, or null when this response completes the list. Always present. Endpoints that serve the whole collection at once always return null." } }, "type": "object", "required": [ "data", "next_cursor" ], "title": "WebhookDeliveryListResponse" }, "WebhookDeliverySource": { "type": "string", "enum": [ "per_job", "default" ], "title": "WebhookDeliverySource", "description": "Which URL resolution created this delivery." }, "WebhookDeliveryStatus": { "type": "string", "enum": [ "PENDING", "DELIVERING", "DELIVERED", "FAILED" ], "title": "WebhookDeliveryStatus", "description": "Where a delivery stands: queued, in flight, or its terminal outcome." }, "WebhookDeliverySummary": { "properties": { "job_id": { "type": "string", "title": "Job Id", "description": "The job whose terminal event this delivers." }, "job_accessible": { "type": "boolean", "title": "Job Accessible", "description": "Whether GET /v3/jobs/{job_id} works for the caller \u2014 false when the job belongs to a different owner than the authenticating key." }, "model": { "type": "string", "title": "Model", "description": "The resolved model id the job ran on." }, "event_type": { "anyOf": [ { "$ref": "#/components/schemas/WebhookEventType" }, { "type": "null" } ], "description": "The terminal event this delivery announces; null until the delivery fires \u2014 a row registered at submit has no outcome to announce while its job is still running." }, "status": { "$ref": "#/components/schemas/WebhookDeliveryStatus" }, "source": { "$ref": "#/components/schemas/WebhookDeliverySource" }, "attempts": { "type": "integer", "title": "Attempts", "description": "Delivery attempts so far, cumulative across replays." }, "redelivery_count": { "type": "integer", "title": "Redelivery Count", "description": "How many operator replays this delivery has had; 0 means every attempt was automatic.", "default": 0 }, "redeliveries": { "items": { "$ref": "#/components/schemas/WebhookRedelivery" }, "type": "array", "title": "Redeliveries", "description": "One entry per operator replay, oldest first \u2014 each holds the delivery's fields as they stood when the replay was requested. Replays recorded before this history existed appear only in `redelivery_count`, so the list can be shorter.", "default": [] }, "last_response_status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Last Response Status", "description": "HTTP status of the most recent attempt; null when it never got a response." }, "last_error": { "anyOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "type": "null" } ], "description": "Why the most recent delivery attempt failed, in the same error envelope `GET /jobs/{job_id}` returns for a failed job: a stable `code` from the shared error vocabulary, a fixed operator-facing `message`, and `retryable`. Null while no attempt has failed. Destination URLs, addresses, headers, credentials, response bodies, and internal exception text are never included \u2014 those stay in Hedra's own logs. `retryable` describes the condition, not what Hedra did: every non-2xx response is retried on the published ladder, so it answers whether replaying this delivery is likely to help. Deliveries that failed before this field became structured report `UNKNOWN`." }, "webhook_url": { "type": "string", "title": "Webhook Url", "description": "The destination endpoint." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "ISO-8601 instant the delivery was registered." }, "last_attempt_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Attempt At", "description": "ISO-8601 instant of the most recent attempt; null before the first one." } }, "type": "object", "required": [ "job_id", "job_accessible", "model", "status", "source", "attempts", "webhook_url", "created_at" ], "title": "WebhookDeliverySummary" }, "WebhookEventType": { "type": "string", "enum": [ "job.completed", "job.failed" ], "title": "WebhookEventType", "description": "The terminal events an outbound webhook announces.\n\nOne delivery carries exactly one of these, chosen from the job's final\nstatus when the delivery fires." }, "WebhookPublicKey": { "properties": { "algorithm": { "type": "string", "title": "Algorithm", "description": "Signature algorithm; always `ed25519`.", "default": "ed25519" }, "public_key": { "type": "string", "title": "Public Key", "description": "Base64-encoded ed25519 public key. Verify each delivery's signature header with it before trusting the payload." } }, "type": "object", "required": [ "public_key" ], "title": "WebhookPublicKey", "description": "The ed25519 public key callers verify outbound webhook signatures with." }, "WebhookRedelivery": { "properties": { "requested_at": { "type": "string", "format": "date-time", "title": "Requested At", "description": "ISO-8601 instant the redelivery was requested." }, "status": { "$ref": "#/components/schemas/WebhookDeliveryStatus" }, "attempts": { "type": "integer", "title": "Attempts", "description": "Cumulative attempt count as it stood when this replay was requested." }, "last_response_status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Last Response Status", "description": "HTTP status of the superseded cycle's last attempt; null when it never got a response." }, "last_error": { "anyOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "type": "null" } ], "description": "Why the most recent delivery attempt failed, in the same error envelope `GET /jobs/{job_id}` returns for a failed job: a stable `code` from the shared error vocabulary, a fixed operator-facing `message`, and `retryable`. Null while no attempt has failed. Destination URLs, addresses, headers, credentials, response bodies, and internal exception text are never included \u2014 those stay in Hedra's own logs. `retryable` describes the condition, not what Hedra did: every non-2xx response is retried on the published ladder, so it answers whether replaying this delivery is likely to help. Deliveries that failed before this field became structured report `UNKNOWN`." }, "last_attempt_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Attempt At", "description": "ISO-8601 instant of the superseded cycle's last attempt." } }, "type": "object", "required": [ "requested_at", "status", "attempts" ], "title": "WebhookRedelivery", "description": "The outcome a replay superseded: the delivery's own fields as they stood\nwhen the operator requested the redelivery. Only finished deliveries can be\nreplayed, so `status` is always terminal (`DELIVERED` / `FAILED`)." }, "WebhookTestResponse": { "properties": { "ok": { "type": "boolean", "title": "Ok", "description": "Whether the test delivery got a 2xx from the endpoint." }, "response_status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Response Status", "description": "HTTP status the endpoint returned; null when the request never got a response." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Why the test failed; null on success." } }, "type": "object", "required": [ "ok" ], "title": "WebhookTestResponse" }, "SubmitResponse": { "properties": { "job_id": { "description": "This job's id \u2014 server-issued, and opaque.", "title": "Job Id", "type": "string" }, "model": { "description": "The resolved model id this job runs on.", "title": "Model", "type": "string" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "status_url": { "description": "Path of this job's status monitor: poll GET /v3/jobs/{job_id}/status for status, progress, and an estimate.", "title": "Status Url", "type": "string" }, "result_url": { "description": "Path of the job resource itself: GET /v3/jobs/{job_id} returns the result envelope, including the outputs once it completes. Also the value of this response's `Location` header.", "title": "Result Url", "type": "string" }, "estimated_completion_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 instant this job is estimated to finish. Null when no estimate exists for the model yet; poll GET /v3/jobs/{job_id}/status for a refreshed one.", "title": "Estimated Completion At" } }, "required": [ "job_id", "model", "status", "status_url", "result_url" ], "title": "SubmitResponse", "type": "object" }, "Input_creatify_aurora": { "description": "Model-specific inputs for `creatify-aurora`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "pattern": "[^\\s\\x1C-\\x1F]", "type": "string", "description": "Generation prompt." }, "resolution": { "description": "Output resolution.", "enum": [ "480p", "720p" ], "type": "string" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "audio": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Driving audio. At most 60s and at most 104.8 MB.", "media_type": "audio", "role": "audio_input", "max_duration_ms": 60000, "max_file_size_bytes": 104857600 } }, "required": [ "audio", "resolution", "start_image" ], "additionalProperties": false }, "SubmitBody_creatify_aurora": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_creatify_aurora" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_dreamina_31": { "description": "Model-specific inputs for `dreamina-31`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "16:10", "10:16", "3:2", "2:3" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "540p", "720p", "1080p" ], "type": "string" }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_dreamina_31": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_dreamina_31" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_elevenlabs_audio_isolation": { "description": "Model-specific inputs for `elevenlabs-audio-isolation`.", "type": "object", "properties": { "audio": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Audio to strip background noise from. At most 104.8 MB.", "media_type": "audio", "role": "audio_input", "max_file_size_bytes": 104857600 } }, "required": [ "audio" ], "additionalProperties": false }, "SubmitBody_elevenlabs_audio_isolation": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_elevenlabs_audio_isolation" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_elevenlabs_english_sts_v2": { "description": "Model-specific inputs for `elevenlabs-english-sts-v2`.", "type": "object", "properties": { "audio": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Speech to re-voice. The delivery, pacing, and timing of this recording are preserved; only the voice changes. At most 104.8 MB.", "media_type": "audio", "role": "audio_input", "max_file_size_bytes": 104857600 }, "voice_id": { "description": "Voice to speak with (`voice_`). List the voices you can use at GET /v3/models/elevenlabs-english-sts-v2/voices; sent with your credentials, the list includes the voices you cloned.", "type": "string" } }, "required": [ "audio", "voice_id" ], "additionalProperties": false }, "SubmitBody_elevenlabs_english_sts_v2": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_elevenlabs_english_sts_v2" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_elevenlabs_flash_multilingual_v2": { "description": "Model-specific inputs for `elevenlabs-flash-multilingual-v2`.", "type": "object", "properties": { "text": { "description": "Generation prompt. At most 40000 characters.", "maxLength": 40000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "stability": { "default": 1.0, "description": "Voice stability. Higher values give a steadier, more consistent delivery; lower values allow more expressive variation between generations. From 0 to 1.", "maximum": 1.0, "minimum": 0.0, "type": "number" }, "speed": { "default": 1.0, "description": "Speech rate multiplier; 1.0 is the voice's natural pace. From 0.7 to 1.2.", "maximum": 1.2, "minimum": 0.7, "type": "number" }, "language": { "type": "string", "description": "Language code; 'auto' by default." }, "voice_id": { "description": "Voice to speak with (`voice_`). List the voices you can use at GET /v3/models/elevenlabs-flash-multilingual-v2/voices; sent with your credentials, the list includes the voices you cloned.", "type": "string" } }, "required": [ "text", "voice_id" ], "additionalProperties": false }, "SubmitBody_elevenlabs_flash_multilingual_v2": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_elevenlabs_flash_multilingual_v2" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_elevenlabs_flash_v2": { "description": "Model-specific inputs for `elevenlabs-flash-v2`.", "type": "object", "properties": { "text": { "description": "Generation prompt. At most 30000 characters.", "maxLength": 30000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "stability": { "default": 1.0, "description": "Voice stability. Higher values give a steadier, more consistent delivery; lower values allow more expressive variation between generations. From 0 to 1.", "maximum": 1.0, "minimum": 0.0, "type": "number" }, "speed": { "default": 1.0, "description": "Speech rate multiplier; 1.0 is the voice's natural pace. From 0.7 to 1.2.", "maximum": 1.2, "minimum": 0.7, "type": "number" }, "language": { "type": "string", "description": "Language code; 'auto' by default." }, "voice_id": { "description": "Voice to speak with (`voice_`). List the voices you can use at GET /v3/models/elevenlabs-flash-v2/voices; sent with your credentials, the list includes the voices you cloned.", "type": "string" } }, "required": [ "text", "voice_id" ], "additionalProperties": false }, "SubmitBody_elevenlabs_flash_v2": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_elevenlabs_flash_v2" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_elevenlabs_multilingual_sts_v2": { "description": "Model-specific inputs for `elevenlabs-multilingual-sts-v2`.", "type": "object", "properties": { "audio": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Speech to re-voice. The delivery, pacing, and timing of this recording are preserved; only the voice changes. At most 104.8 MB.", "media_type": "audio", "role": "audio_input", "max_file_size_bytes": 104857600 }, "voice_id": { "description": "Voice to speak with (`voice_`). List the voices you can use at GET /v3/models/elevenlabs-multilingual-sts-v2/voices; sent with your credentials, the list includes the voices you cloned.", "type": "string" } }, "required": [ "audio", "voice_id" ], "additionalProperties": false }, "SubmitBody_elevenlabs_multilingual_sts_v2": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_elevenlabs_multilingual_sts_v2" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_elevenlabs_multilingual_v2": { "description": "Model-specific inputs for `elevenlabs-multilingual-v2`.", "type": "object", "properties": { "text": { "description": "Generation prompt. At most 10000 characters.", "maxLength": 10000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "stability": { "default": 1.0, "description": "Voice stability. Higher values give a steadier, more consistent delivery; lower values allow more expressive variation between generations. From 0 to 1.", "maximum": 1.0, "minimum": 0.0, "type": "number" }, "speed": { "default": 1.0, "description": "Speech rate multiplier; 1.0 is the voice's natural pace. From 0.7 to 1.2.", "maximum": 1.2, "minimum": 0.7, "type": "number" }, "language": { "type": "string", "description": "Language code; 'auto' by default." }, "voice_id": { "description": "Voice to speak with (`voice_`). List the voices you can use at GET /v3/models/elevenlabs-multilingual-v2/voices; sent with your credentials, the list includes the voices you cloned.", "type": "string" } }, "required": [ "text", "voice_id" ], "additionalProperties": false }, "SubmitBody_elevenlabs_multilingual_v2": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_elevenlabs_multilingual_v2" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_elevenlabs_music": { "description": "Model-specific inputs for `elevenlabs-music`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "duration_ms": { "description": "Length of the generated track, in milliseconds. Billed as whole seconds, rounded up. From 3000 to 600000.", "maximum": 600000, "minimum": 3000, "type": "integer" }, "lyrics": { "maxLength": 10000, "type": "string", "description": "Words for the track to sing. Sent to the provider inside the prompt, which reads lyrics from the prompt text and places them across the requested length. Cannot be combined with `force_instrumental`. At most 10000 characters." }, "force_instrumental": { "default": false, "description": "Compose without vocals.", "type": "boolean" } }, "required": [ "duration_ms", "prompt" ], "additionalProperties": false }, "SubmitBody_elevenlabs_music": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_elevenlabs_music" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_elevenlabs_sound_effects": { "description": "Model-specific inputs for `elevenlabs-sound-effects`.", "type": "object", "properties": { "text": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "duration_ms": { "description": "Length of the generated sound, in milliseconds. Billed as whole seconds, rounded up. From 500 to 30000.", "maximum": 30000, "minimum": 500, "type": "integer" }, "prompt_influence": { "default": 0.3, "description": "How literally the model reads the description; higher values track it more closely and lower values leave the model more latitude. From 0 to 1.", "maximum": 1.0, "minimum": 0.0, "type": "number" }, "loop": { "default": false, "description": "Generate a sound that loops seamlessly end to end.", "type": "boolean" } }, "required": [ "duration_ms", "text" ], "additionalProperties": false }, "SubmitBody_elevenlabs_sound_effects": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_elevenlabs_sound_effects" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_elevenlabs_v3": { "description": "Model-specific inputs for `elevenlabs-v3`.", "type": "object", "properties": { "text": { "description": "Generation prompt. At most 5000 characters.", "maxLength": 5000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "stability": { "default": 1.0, "description": "Voice stability. Higher values give a steadier, more consistent delivery; lower values allow more expressive variation between generations. From 0 to 1.", "maximum": 1.0, "minimum": 0.0, "type": "number" }, "speed": { "default": 1.0, "description": "Speech rate multiplier; 1.0 is the voice's natural pace. From 0.7 to 1.2.", "maximum": 1.2, "minimum": 0.7, "type": "number" }, "language": { "type": "string", "description": "Language code; 'auto' by default." }, "voice_id": { "description": "Voice to speak with (`voice_`). List the voices you can use at GET /v3/models/elevenlabs-v3/voices; sent with your credentials, the list includes the voices you cloned.", "type": "string" } }, "required": [ "text", "voice_id" ], "additionalProperties": false }, "SubmitBody_elevenlabs_v3": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_elevenlabs_v3" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_elevenlabs_voice_clone": { "description": "Model-specific inputs for `elevenlabs-voice-clone`.", "type": "object", "properties": { "audio": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Speech sample of the voice to clone. Longer, cleaner samples of a single speaker clone better. At most 104.8 MB.", "media_type": "audio", "role": "audio_input", "max_file_size_bytes": 104857600 }, "name": { "description": "Name for the created voice. Shown wherever the voice is listed; it does not affect how the voice sounds. At least 1 character.", "minLength": 1, "type": "string" } }, "required": [ "audio", "name" ], "additionalProperties": false }, "SubmitBody_elevenlabs_voice_clone": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_elevenlabs_voice_clone" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_eyeline_id_relight": { "description": "Model-specific inputs for `eyeline-id-relight`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Source video. From 1s to 8s and at most 524.2 MB.", "media_type": "video", "role": "input_video", "min_duration_ms": 1000, "max_duration_ms": 8000, "max_file_size_bytes": 524288000 }, "images": { "description": "An edited copy of the source video's first frame. Exactly one; the clip is regenerated to match it. Exactly 1 image, at most 10.4 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 1, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 10485760 } }, "required": [ "images", "prompt", "source_video" ], "additionalProperties": false }, "SubmitBody_eyeline_id_relight": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_eyeline_id_relight" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_eyeline_id_restyle": { "description": "Model-specific inputs for `eyeline-id-restyle`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Source video. From 1s to 8s and at most 524.2 MB.", "media_type": "video", "role": "input_video", "min_duration_ms": 1000, "max_duration_ms": 8000, "max_file_size_bytes": 524288000 }, "images": { "description": "An edited copy of the source video's first frame. Exactly one; the clip is regenerated to match it. Exactly 1 image, at most 10.4 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 1, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 10485760 } }, "required": [ "images", "prompt", "source_video" ], "additionalProperties": false }, "SubmitBody_eyeline_id_restyle": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_eyeline_id_restyle" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_flux_11_pro": { "description": "Model-specific inputs for `flux-11-pro`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "1:3", "2:3", "3:1", "3:2", "3:4", "4:3", "16:9", "9:16", "10:16", "16:10" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "540p", "720p", "1080p", "1440p (2K QHD)", "2160p (4K UHD)" ], "type": "string" }, "output_format": { "enum": [ "jpeg", "png" ], "type": "string", "description": "Output image format." }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_flux_11_pro": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_flux_11_pro" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_flux_11_ultra": { "description": "Model-specific inputs for `flux-11-ultra`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9", "9:21", "3:2", "2:3" ], "type": "string" }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "fixed" ] }, "output_format": { "enum": [ "jpeg", "png" ], "type": "string", "description": "Output image format." }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." } }, "required": [ "aspect_ratio", "prompt" ], "additionalProperties": false }, "SubmitBody_flux_11_ultra": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_flux_11_ultra" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_flux_3": { "description": "Model-specific inputs for `flux-3`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "auto", "21:9", "2:1", "16:9", "4:3", "1:1", "3:4", "9:16" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "720p", "1080p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000, 16000, 17000, 18000, 19000, 20000 ], "type": "integer" }, "generate_audio": { "default": true, "description": "Whether to generate native audio for the video.", "type": "boolean" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. At most 10.4 MB.", "media_type": "image", "role": "end_frame", "max_file_size_bytes": 10485760 } }, "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution", "start_image" ], "properties": { "end_image": false } }, { "required": [ "aspect_ratio", "duration_ms", "end_image", "prompt", "resolution", "start_image" ] }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "properties": { "end_image": false, "start_image": false } } ] }, "SubmitBody_flux_3": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_flux_3" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_flux_3_video_upscaler_creative": { "description": "Model-specific inputs for `flux-3-video-upscaler-creative`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "The video to upscale. At most 20s and at most 524.2 MB.", "media_type": "video", "role": "input_video", "max_duration_ms": 20000, "max_file_size_bytes": 524288000 }, "resolution": { "description": "Output resolution.", "enum": [ "1080p", "2K", "4K" ], "type": "string" } }, "required": [ "resolution", "source_video" ], "additionalProperties": false }, "SubmitBody_flux_3_video_upscaler_creative": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_flux_3_video_upscaler_creative" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_flux_3_video_upscaler_precise": { "description": "Model-specific inputs for `flux-3-video-upscaler-precise`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "The video to upscale. At most 20s and at most 524.2 MB.", "media_type": "video", "role": "input_video", "max_duration_ms": 20000, "max_file_size_bytes": 524288000 }, "resolution": { "description": "Output resolution.", "enum": [ "1080p", "2K", "4K" ], "type": "string" } }, "required": [ "resolution", "source_video" ], "additionalProperties": false }, "SubmitBody_flux_3_video_upscaler_precise": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_flux_3_video_upscaler_precise" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_flux_dev": { "description": "Model-specific inputs for `flux-dev`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "1:3", "2:3", "3:1", "3:2", "3:4", "4:3", "16:9", "9:16", "10:16", "16:10" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "540p", "720p", "1080p", "1440p (2K QHD)", "2160p (4K UHD)" ], "type": "string" }, "output_format": { "enum": [ "jpeg", "png" ], "type": "string", "description": "Output image format." }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." }, "guidance_scale": { "maximum": 20.0, "minimum": 1.0, "type": "number", "description": "How closely the model follows the prompt. From 1 to 20." }, "num_inference_steps": { "maximum": 50, "minimum": 1, "type": "integer", "description": "Denoising steps to run. From 1 to 50." } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_flux_dev": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_flux_dev" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_flux_kontext_max": { "description": "Model-specific inputs for `flux-kontext-max`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "images": { "description": "The single source image to edit. Exactly 1 image, at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 1, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "output_format": { "enum": [ "jpeg", "png" ], "type": "string", "description": "Output image format." }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9", "9:21", "3:2", "2:3" ], "type": "string" }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "fixed" ] } }, "required": [ "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "images", "prompt" ], "properties": { "aspect_ratio": false, "resolution": false } }, { "required": [ "aspect_ratio", "prompt" ], "properties": { "images": false } } ] }, "SubmitBody_flux_kontext_max": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_flux_kontext_max" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_flux_kontext_pro": { "description": "Model-specific inputs for `flux-kontext-pro`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "images": { "description": "The single source image to edit. Exactly 1 image, at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 1, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "output_format": { "enum": [ "jpeg", "png" ], "type": "string", "description": "Output image format." }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9", "9:21", "3:2", "2:3" ], "type": "string" }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "fixed" ] } }, "required": [ "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "images", "prompt" ], "properties": { "aspect_ratio": false, "resolution": false } }, { "required": [ "aspect_ratio", "prompt" ], "properties": { "images": false } } ] }, "SubmitBody_flux_kontext_pro": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_flux_kontext_pro" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_flux2_flex": { "description": "Model-specific inputs for `flux2-flex`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "images": { "description": "Images to edit or blend. 1 to 8 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 8, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "output_format": { "enum": [ "jpeg", "png" ], "type": "string", "description": "Output image format." }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." }, "guidance": { "maximum": 10.0, "minimum": 1.5, "type": "number", "description": "How closely the model follows the prompt. From 1.5 to 10." }, "steps": { "maximum": 50, "minimum": 2, "type": "integer", "description": "Denoising steps to run. From 2 to 50." } }, "required": [ "aspect_ratio", "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "images", "prompt" ] }, { "required": [ "aspect_ratio", "prompt" ], "properties": { "images": false } } ] }, "SubmitBody_flux2_flex": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_flux2_flex" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_flux2_klein_9b": { "description": "Model-specific inputs for `flux2-klein-9b`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "images": { "description": "Images to edit or blend. 1 to 4 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 4, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "output_format": { "enum": [ "jpeg", "png", "webp" ], "type": "string", "description": "Output image format." }, "negative_prompt": { "type": "string", "description": "What to avoid in the generated image." }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." }, "guidance_scale": { "maximum": 20.0, "minimum": 0.0, "type": "number", "description": "How closely the model follows the prompt. From 0 to 20." }, "num_inference_steps": { "maximum": 50, "minimum": 4, "type": "integer", "description": "Denoising steps to run. From 4 to 50." } }, "required": [ "aspect_ratio", "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "images", "prompt" ] }, { "required": [ "aspect_ratio", "prompt" ], "properties": { "images": false } } ] }, "SubmitBody_flux2_klein_9b": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_flux2_klein_9b" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_flux2_max": { "description": "Model-specific inputs for `flux2-max`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "images": { "description": "Images to edit or blend. 1 to 8 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 8, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "output_format": { "enum": [ "jpeg", "png" ], "type": "string", "description": "Output image format." }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." } }, "required": [ "aspect_ratio", "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "images", "prompt" ] }, { "required": [ "aspect_ratio", "prompt" ], "properties": { "images": false } } ] }, "SubmitBody_flux2_max": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_flux2_max" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_flux2_pro": { "description": "Model-specific inputs for `flux2-pro`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "images": { "description": "Images to edit or blend. 1 to 8 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 8, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "output_format": { "enum": [ "jpeg", "png" ], "type": "string", "description": "Output image format." }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." } }, "required": [ "aspect_ratio", "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "images", "prompt" ] }, { "required": [ "aspect_ratio", "prompt" ], "properties": { "images": false } } ] }, "SubmitBody_flux2_pro": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_flux2_pro" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_gemini_omni_flash": { "description": "Model-specific inputs for `gemini-omni-flash`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16" ], "type": "string" }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "720p" ] }, "duration_ms": { "enum": [ 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000 ], "type": "integer", "description": "Duration in ms." }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Source video. From 1s to 10.15s and at most 524.2 MB.", "media_type": "video", "role": "input_video", "min_duration_ms": 1000, "max_duration_ms": 10150, "max_file_size_bytes": 524288000 }, "images": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 10, "minItems": 1, "type": "array", "description": "Reference images. 1 to 10 images, each at most 10.4 MB.", "media_type": "image", "role": "reference", "max_file_size_bytes": 10485760 }, "videos": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 3, "minItems": 1, "type": "array", "description": "Reference videos. 1 to 3 videos, each at most 10.15s and at most 524.2 MB.", "media_type": "video", "role": "reference", "max_duration_ms": 10150, "max_file_size_bytes": 524288000 } }, "required": [ "aspect_ratio", "prompt" ], "additionalProperties": false }, "SubmitBody_gemini_omni_flash": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_gemini_omni_flash" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_gemini_omni_flash_11": { "description": "Model-specific inputs for `gemini-omni-flash-11`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "360p", "720p", "1080p", "4k" ], "type": "string" }, "duration_ms": { "enum": [ 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000 ], "type": "integer", "description": "Duration in ms." }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. At most 10.4 MB.", "media_type": "image", "role": "end_frame", "max_file_size_bytes": 10485760 }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Source video. From 1s to 10.15s and at most 524.2 MB.", "media_type": "video", "role": "input_video", "min_duration_ms": 1000, "max_duration_ms": 10150, "max_file_size_bytes": 524288000 }, "images": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 10, "minItems": 1, "type": "array", "description": "Reference images. 1 to 10 images, each at most 10.4 MB.", "media_type": "image", "role": "reference", "max_file_size_bytes": 10485760 }, "videos": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 3, "minItems": 1, "type": "array", "description": "Reference videos. 1 to 3 videos, each at most 10.15s and at most 524.2 MB.", "media_type": "video", "role": "reference", "max_duration_ms": 10150, "max_file_size_bytes": 524288000 } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_gemini_omni_flash_11": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_gemini_omni_flash_11" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_gpt_image_15": { "description": "Model-specific inputs for `gpt-image-15`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt. At most 32000 characters.", "maxLength": 32000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "3:2", "2:3" ], "type": "string" }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "fixed" ] }, "images": { "description": "Images to edit or blend. 1 to 16 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 16, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "output_format": { "enum": [ "jpeg", "png", "webp" ], "type": "string", "description": "Output image format." } }, "required": [ "aspect_ratio", "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "images", "prompt" ] }, { "required": [ "aspect_ratio", "prompt" ], "properties": { "images": false } } ] }, "SubmitBody_gpt_image_15": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_gpt_image_15" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_gpt_image_2": { "description": "Model-specific inputs for `gpt-image-2`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt. At most 32000 characters.", "maxLength": 32000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "1K", "2K", "4K" ], "type": "string" }, "images": { "description": "Images to edit or blend. 1 to 16 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 16, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "output_format": { "enum": [ "jpeg", "png", "webp" ], "type": "string", "description": "Output image format." }, "quality": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Quality level to generate at. `low` \u2014 the quickest and cheapest pass, for drafts, thumbnails, and rapid exploration. `medium` \u2014 balanced cost and fidelity, for everyday work and iterative refinement. `high` \u2014 the most rendering effort, for final deliverables and text-heavy designs.", "default": "medium" } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "images", "prompt", "resolution" ] }, { "required": [ "aspect_ratio", "prompt", "resolution" ], "properties": { "images": false } } ] }, "SubmitBody_gpt_image_2": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_gpt_image_2" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_gpt_image_2.5_flare": { "description": "Model-specific inputs for `gpt-image-2.5-flare`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt. At most 32000 characters.", "maxLength": 32000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "1K", "2K", "4K" ], "type": "string" }, "output_format": { "enum": [ "jpeg", "png", "webp" ], "type": "string", "description": "Output image format." }, "images": { "description": "Images to edit or blend. 1 to 16 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 16, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "quality": { "type": "string", "enum": [ "auto", "low", "medium", "high" ], "description": "Quality level to generate at. `auto` \u2014 automatically selects rendering quality for the prompt. `low` \u2014 low rendering quality for the Flare model. `medium` \u2014 medium rendering quality for the Flare model. `high` \u2014 high rendering quality for the Flare model.", "default": "auto" } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "images", "prompt", "resolution" ] }, { "required": [ "aspect_ratio", "prompt", "resolution" ], "properties": { "images": false } } ] }, "SubmitBody_gpt_image_2.5_flare": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_gpt_image_2.5_flare" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_gpt_image_2.5_sunburst": { "description": "Model-specific inputs for `gpt-image-2.5-sunburst`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt. At most 32000 characters.", "maxLength": 32000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "1K", "2K", "4K" ], "type": "string" }, "output_format": { "enum": [ "jpeg", "png", "webp" ], "type": "string", "description": "Output image format." }, "images": { "description": "Images to edit or blend. 1 to 16 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 16, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "quality": { "type": "string", "enum": [ "auto", "low", "medium", "high" ], "description": "Quality level to generate at. `auto` \u2014 automatically selects rendering quality for the prompt. `low` \u2014 low rendering quality for the Sunburst model. `medium` \u2014 medium rendering quality for the Sunburst model. `high` \u2014 high rendering quality for the Sunburst model.", "default": "auto" } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "images", "prompt", "resolution" ] }, { "required": [ "aspect_ratio", "prompt", "resolution" ], "properties": { "images": false } } ] }, "SubmitBody_gpt_image_2.5_sunburst": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_gpt_image_2.5_sunburst" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_grok_imagine": { "description": "Model-specific inputs for `grok-imagine`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt. At most 8000 characters.", "maxLength": 8000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "images": { "description": "Images to edit or blend. 1 to 3 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 3, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "output_format": { "enum": [ "jpeg", "png", "webp" ], "type": "string", "description": "Output image format." }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "auto", "2:1", "20:9", "19.5:9", "16:9", "4:3", "3:2", "1:1", "2:3", "3:4", "9:16", "9:19.5", "9:20", "1:2" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "1k", "2k" ], "type": "string" }, "quality": { "type": "string", "enum": [ "standard", "quality" ], "description": "Quality level to generate at. `standard` \u2014 the base tier, at a flat rate whatever the output size. `quality` \u2014 xAI's higher-fidelity tier, and the only one offering 2k.", "default": "standard" } }, "required": [ "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "images", "prompt" ], "properties": { "aspect_ratio": false, "quality": { "enum": [ "standard" ] }, "resolution": false } }, { "required": [ "aspect_ratio", "images", "prompt", "resolution" ], "properties": { "quality": { "enum": [ "quality" ] } } }, { "required": [ "aspect_ratio", "prompt", "resolution" ], "properties": { "aspect_ratio": { "enum": [ "2:1", "20:9", "19.5:9", "16:9", "4:3", "3:2", "1:1", "2:3", "3:4", "9:16", "9:19.5", "9:20", "1:2" ] }, "images": false, "quality": { "enum": [ "quality" ] } } }, { "required": [ "aspect_ratio", "prompt" ], "properties": { "aspect_ratio": { "enum": [ "2:1", "20:9", "19.5:9", "16:9", "4:3", "3:2", "1:1", "2:3", "3:4", "9:16", "9:19.5", "9:20", "1:2" ] }, "images": false, "quality": { "enum": [ "standard" ] }, "resolution": false } } ] }, "SubmitBody_grok_imagine": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_grok_imagine" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_grok_imagine_20": { "description": "Model-specific inputs for `grok-imagine-20`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt. At most 8000 characters.", "maxLength": 8000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "images": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 3, "minItems": 1, "type": "array", "description": "Images to edit or blend; omit to render from the prompt alone. 1 to 3 images, each at most 30 MB.", "media_type": "image", "role": "reference", "max_file_size_bytes": 30000000 }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "2:1", "20:9", "19.5:9", "16:9", "4:3", "3:2", "1:1", "2:3", "3:4", "9:16", "9:19.5", "9:20", "1:2" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "1k", "2k" ], "type": "string" }, "output_format": { "enum": [ "jpeg", "png", "webp" ], "type": "string", "description": "Output image format." } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_grok_imagine_20": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_grok_imagine_20" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_grok_video": { "description": "Model-specific inputs for `grok-video`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 4096 characters.", "maxLength": 4096, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "auto", "16:9", "4:3", "3:2", "1:1", "2:3", "3:4", "9:16" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "480p", "720p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000 ], "type": "integer" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 } }, "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution", "start_image" ] }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "properties": { "aspect_ratio": { "enum": [ "16:9", "4:3", "3:2", "1:1", "2:3", "3:4", "9:16" ] }, "start_image": false } } ] }, "SubmitBody_grok_video": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_grok_video" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_happy_horse": { "description": "Model-specific inputs for `happy-horse`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. From 1 to 2500 characters.", "maxLength": 2500, "minLength": 1, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "720p", "1080p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000 ], "type": "integer" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At least 300px on each side and at most 10 MB.", "media_type": "image", "role": "start_frame", "min_dimension_px": 300, "max_file_size_bytes": 10000000 }, "images": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 9, "minItems": 1, "type": "array", "description": "Reference images. 1 to 9 images, each at least 400px on each side and at most 10 MB.", "media_type": "image", "role": "reference", "min_dimension_px": 400, "max_file_size_bytes": 10000000 }, "seed": { "maximum": 2147483647, "minimum": 0, "type": "integer", "description": "Seed for reproducible output; omit for a random seed. From 0 to 2147483647." } }, "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_happy_horse": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_happy_horse" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_hedra_avatar": { "description": "Model-specific inputs for `hedra-avatar`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "4:3", "3:4", "16:9", "9:16", "9:21", "21:9" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "540p", "720p", "1080p" ], "type": "string" }, "duration_ms": { "maximum": 600000, "type": "integer", "description": "Duration in ms. At most 600000.", "guidance": "Optional. Leave it out and the video runs as long as the audio you supply. Give a value and the audio is trimmed, or padded with silence, to that length." }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "audio": { "anyOf": [ { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 4, "minItems": 1, "type": "array" } ], "description": "Driving audio: a single reference, or a list of references for multi-speaker generation \u2014 one audio per speaker, played in list order. 1 to 4 audio files, each from 0.5s to 600s and at most 104.8 MB.", "media_type": "audio", "role": "audio_input", "min_duration_ms": 500, "max_duration_ms": 600000, "max_file_size_bytes": 104857600 }, "bounding_box_target": { "anyOf": [ { "maxItems": 2, "minItems": 2, "prefixItems": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "maximum": 1.0, "minimum": 0.0, "type": "number" } ], "type": "array" }, { "items": { "maxItems": 2, "minItems": 2, "prefixItems": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "maximum": 1.0, "minimum": 0.0, "type": "number" } ], "type": "array" }, "type": "array" } ], "description": "Speaker position(s) in the start frame, as normalized [x, y] image coordinates (0-1 from the top-left).", "guidance": "Optional for a single speaker: one [x, y] point selects who speaks in a frame with several people. Required for multi-speaker: pass `audio` as a list and one point per audio, in the same order." } }, "required": [ "aspect_ratio", "audio", "prompt", "resolution", "start_image" ], "additionalProperties": false }, "SubmitBody_hedra_avatar": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_hedra_avatar" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_hedra_character_3": { "description": "Model-specific inputs for `hedra-character-3`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "4:3", "3:4", "16:9", "9:16", "9:21", "21:9" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "540p", "720p", "1080p" ], "type": "string" }, "duration_ms": { "maximum": 600000, "type": "integer", "description": "Duration in ms. At most 600000.", "guidance": "Optional. Leave it out and the video runs as long as the audio you supply. Give a value and the audio is trimmed, or padded with silence, to that length." }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "audio": { "anyOf": [ { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 4, "minItems": 1, "type": "array" } ], "description": "Driving audio: a single reference, or a list of references for multi-speaker generation \u2014 one audio per speaker, played in list order. 1 to 4 audio files, each from 0.5s to 600s and at most 104.8 MB.", "media_type": "audio", "role": "audio_input", "min_duration_ms": 500, "max_duration_ms": 600000, "max_file_size_bytes": 104857600 }, "bounding_box_target": { "anyOf": [ { "maxItems": 2, "minItems": 2, "prefixItems": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "maximum": 1.0, "minimum": 0.0, "type": "number" } ], "type": "array" }, { "items": { "maxItems": 2, "minItems": 2, "prefixItems": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "maximum": 1.0, "minimum": 0.0, "type": "number" } ], "type": "array" }, "type": "array" } ], "description": "Speaker position(s) in the start frame, as normalized [x, y] image coordinates (0-1 from the top-left).", "guidance": "Optional for a single speaker: one [x, y] point selects who speaks in a frame with several people. Required for multi-speaker: pass `audio` as a list and one point per audio, in the same order." } }, "required": [ "aspect_ratio", "audio", "prompt", "resolution", "start_image" ], "additionalProperties": false }, "SubmitBody_hedra_character_3": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_hedra_character_3" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_heygen_photo_avatar_4": { "description": "Model-specific inputs for `heygen-photo-avatar-4`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "pattern": "[^\\s\\x1C-\\x1F]", "type": "string", "description": "Generation prompt." }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:5", "5:4", "1:1", "auto" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "360p", "480p", "540p", "720p", "1080p" ], "type": "string" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "audio": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Driving audio. At most 104.8 MB.", "media_type": "audio", "role": "audio_input", "max_file_size_bytes": 104857600 } }, "required": [ "aspect_ratio", "audio", "resolution", "start_image" ], "additionalProperties": false }, "SubmitBody_heygen_photo_avatar_4": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_heygen_photo_avatar_4" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_hidream_o1_image": { "description": "Model-specific inputs for `hidream-o1-image`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt. At least 1 character.", "minLength": 1, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "images": { "description": "Images to edit or blend. 1 to 10 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 10, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "output_format": { "enum": [ "jpeg", "png", "webp" ], "type": "string", "description": "Output image format." }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." }, "guidance_scale": { "maximum": 20.0, "minimum": 0.0, "type": "number", "description": "How closely the model follows the prompt. From 0 to 20." }, "num_inference_steps": { "maximum": 50, "minimum": 1, "type": "integer", "description": "Denoising steps to run. From 1 to 50." }, "resolution": { "description": "Output resolution.", "enum": [ "540p", "720p", "1080p" ], "type": "string" }, "quality": { "type": "string", "enum": [ "standard", "dev" ], "description": "Quality level to generate at. `standard` \u2014 the full model, at 50 denoising steps. `dev` \u2014 HiDream's distilled checkpoint, at 28 denoising steps instead of 50 \u2014 quicker and cheaper for the same prompt.", "default": "standard" } }, "required": [ "aspect_ratio", "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "images", "prompt" ], "properties": { "resolution": false } }, { "required": [ "aspect_ratio", "prompt", "resolution" ], "properties": { "images": false } } ] }, "SubmitBody_hidream_o1_image": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_hidream_o1_image" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_ideogram_v2": { "description": "Model-specific inputs for `ideogram-v2`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "1:3", "2:3", "3:1", "3:2", "3:4", "4:3", "16:9", "9:16", "10:16", "16:10" ], "type": "string" }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "fixed" ] }, "negative_prompt": { "type": "string", "description": "What to avoid in the generated image." }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." } }, "required": [ "aspect_ratio", "prompt" ], "additionalProperties": false }, "SubmitBody_ideogram_v2": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_ideogram_v2" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_ideogram_v4": { "description": "Model-specific inputs for `ideogram-v4`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "720p", "1440p (2K QHD)", "2160p (4K UHD)" ], "type": "string" }, "output_format": { "enum": [ "jpeg", "png" ], "type": "string", "description": "Output image format." }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." }, "quality": { "type": "string", "enum": [ "turbo", "balanced", "quality" ], "description": "Quality level to generate at. `turbo` \u2014 the least rendering effort, for quick exploration. `balanced` \u2014 middle rendering effort, the everyday choice. `quality` \u2014 the most rendering effort, for poster-ready text and layout.", "default": "balanced" } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_ideogram_v4": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_ideogram_v4" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_imagen3": { "description": "Model-specific inputs for `imagen3`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "fixed" ] } }, "required": [ "aspect_ratio", "prompt" ], "additionalProperties": false }, "SubmitBody_imagen3": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_imagen3" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_imagen4": { "description": "Model-specific inputs for `imagen4`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt. At most 5000 characters.", "maxLength": 5000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "1K", "2K" ], "type": "string" } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_imagen4": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_imagen4" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_kling_16": { "description": "Model-specific inputs for `kling-16`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 2500 characters.", "maxLength": 2500, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "type": "string", "description": "Output aspect ratio.", "enum": [ "16:9" ] }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "1080p", "720p" ] }, "duration_ms": { "type": "integer", "description": "Duration in ms.", "enum": [ 5000 ] }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "negative_prompt": { "maxLength": 2500, "type": "string", "description": "What to avoid in the generated video. At most 2500 characters." }, "cfg_scale": { "maximum": 1.0, "minimum": 0.0, "type": "number", "description": "How closely the model follows the prompt. From 0 to 1." } }, "required": [ "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "prompt", "start_image" ], "properties": { "resolution": { "enum": [ "1080p" ] } } }, { "required": [ "prompt" ], "properties": { "resolution": { "enum": [ "720p" ] }, "start_image": false } } ] }, "SubmitBody_kling_16": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_kling_16" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_kling_21_master": { "description": "Model-specific inputs for `kling-21-master`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 2500 characters.", "maxLength": 2500, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1" ], "type": "string" }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "720p" ] }, "duration_ms": { "description": "Duration in ms.", "enum": [ 5000, 10000 ], "type": "integer" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "negative_prompt": { "maxLength": 2500, "type": "string", "description": "What to avoid in the generated video. At most 2500 characters." }, "cfg_scale": { "maximum": 1.0, "minimum": 0.0, "type": "number", "description": "How closely the model follows the prompt. From 0 to 1." } }, "required": [ "aspect_ratio", "duration_ms", "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "duration_ms", "prompt", "start_image" ] }, { "required": [ "aspect_ratio", "duration_ms", "prompt" ], "properties": { "start_image": false } } ] }, "SubmitBody_kling_21_master": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_kling_21_master" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_kling_25_turbo": { "description": "Model-specific inputs for `kling-25-turbo`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 2500 characters.", "maxLength": 2500, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1" ], "type": "string" }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "1080p" ] }, "duration_ms": { "description": "Duration in ms.", "enum": [ 5000, 10000 ], "type": "integer" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "negative_prompt": { "maxLength": 2500, "type": "string", "description": "What to avoid in the generated video. At most 2500 characters." }, "cfg_scale": { "maximum": 1.0, "minimum": 0.0, "type": "number", "description": "How closely the model follows the prompt. From 0 to 1." } }, "required": [ "aspect_ratio", "duration_ms", "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "duration_ms", "prompt", "start_image" ] }, { "required": [ "aspect_ratio", "duration_ms", "prompt" ], "properties": { "start_image": false } } ] }, "SubmitBody_kling_25_turbo": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_kling_25_turbo" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_kling_26_motion_control": { "description": "Model-specific inputs for `kling-26-motion-control`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "maxLength": 2500, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string", "description": "Generation prompt. At most 2500 characters." }, "character_orientation": { "default": "video", "description": "Whether the output character's orientation follows the reference video ('video' \u2014 better for complex motion) or the character image ('image' \u2014 better for camera movement). Also caps the source video: 30s for 'video', 10s for 'image'.", "enum": [ "image", "video" ], "type": "string" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Source video. From 3s to 30s and at most 524.2 MB.", "media_type": "video", "role": "input_video", "min_duration_ms": 3000, "max_duration_ms": 30000, "max_file_size_bytes": 524288000 }, "resolution": { "type": "string", "enum": [ "720p", "1080p" ], "description": "Output resolution to generate at." } }, "required": [ "resolution", "source_video", "start_image" ], "additionalProperties": false }, "SubmitBody_kling_26_motion_control": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_kling_26_motion_control" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_kling_26_pro": { "description": "Model-specific inputs for `kling-26-pro`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 2500 characters.", "maxLength": 2500, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1" ], "type": "string" }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "1080p" ] }, "duration_ms": { "description": "Duration in ms.", "enum": [ 5000, 10000 ], "type": "integer" }, "generate_audio": { "default": true, "description": "Whether to generate native audio for the video.", "type": "boolean" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "negative_prompt": { "maxLength": 2500, "type": "string", "description": "What to avoid in the generated video. At most 2500 characters." }, "cfg_scale": { "maximum": 1.0, "minimum": 0.0, "type": "number", "description": "How closely the model follows the prompt. From 0 to 1." } }, "required": [ "aspect_ratio", "duration_ms", "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "duration_ms", "prompt", "start_image" ], "properties": { "cfg_scale": false } }, { "required": [ "aspect_ratio", "duration_ms", "prompt" ], "properties": { "start_image": false } } ] }, "SubmitBody_kling_26_pro": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_kling_26_pro" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_kling_ai_avatar_v2": { "description": "Model-specific inputs for `kling-ai-avatar-v2`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "maxLength": 2500, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string", "description": "Generation prompt. At most 2500 characters." }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1" ], "type": "string" }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "720p" ] }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "audio": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Driving audio. From 2s to 60.15s and at most 5 MB.", "media_type": "audio", "role": "audio_input", "min_duration_ms": 2000, "max_file_size_bytes": 5000000, "max_duration_ms": 60150 }, "quality": { "type": "string", "enum": [ "standard", "pro" ], "description": "Quality level to generate at. `standard` \u2014 the base tier. `pro` \u2014 sharper detail and steadier motion at the same resolution, at a higher rate.", "default": "standard" } }, "required": [ "aspect_ratio", "audio", "start_image" ], "additionalProperties": false }, "SubmitBody_kling_ai_avatar_v2": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_kling_ai_avatar_v2" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_kling_o1": { "description": "Model-specific inputs for `kling-o1`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 2500 characters.", "maxLength": 2500, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1" ], "type": "string" }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "1080p" ] }, "duration_ms": { "description": "Duration in ms.", "enum": [ 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000 ], "type": "integer" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. At most 10.4 MB.", "media_type": "image", "role": "end_frame", "max_file_size_bytes": 10485760 }, "images": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 3, "minItems": 1, "type": "array", "description": "Reference images. 1 to 3 images, each at most 10.4 MB.", "media_type": "image", "role": "reference", "max_file_size_bytes": 10485760 } }, "required": [ "aspect_ratio", "duration_ms", "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "duration_ms", "prompt", "start_image" ] }, { "required": [ "aspect_ratio", "duration_ms", "images", "prompt" ] } ] }, "SubmitBody_kling_o1": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_kling_o1" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_kling_o3": { "description": "Model-specific inputs for `kling-o3`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "maxLength": 2500, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string", "description": "Generation prompt. At most 2500 characters." }, "multi_prompt": { "items": { "additionalProperties": false, "description": "One shot of a published multi-shot storyboard.", "properties": { "prompt": { "description": "The prompt for this shot.", "type": "string" }, "duration_ms": { "default": 5000, "description": "Duration of this shot in milliseconds.", "enum": [ 1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000 ], "type": "integer" } }, "required": [ "prompt" ], "type": "object" }, "maxItems": 6, "minItems": 1, "type": "array", "description": "Multi-shot storyboard; each shot carries its own prompt and duration. Shot durations must sum to at most 15000 ms, and the storyboard replaces `prompt` \u2014 supply one or the other, never both. A shot's prompt has no length limit, unlike the single `prompt` field. 1 to 6 items." }, "shot_type": { "enum": [ "customize", "intelligent" ], "type": "string", "description": "How a multi-shot storyboard is cut. 'customize' honours each shot's declared duration; 'intelligent' lets the model determine the shot structure. Ignored unless `multi_prompt` is supplied." }, "generate_audio": { "default": true, "description": "Whether to generate native audio for the video.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "1080p", "4K", "720p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000 ], "type": "integer" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. At most 10.4 MB.", "media_type": "image", "role": "end_frame", "max_file_size_bytes": 10485760 }, "images": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 3, "minItems": 1, "type": "array", "description": "Reference images. 1 to 3 images, each at most 10.4 MB.", "media_type": "image", "role": "reference", "max_file_size_bytes": 10485760 }, "quality": { "type": "string", "enum": [ "standard", "pro" ], "description": "Quality level to generate at. `standard` \u2014 the 720p tier. `pro` \u2014 the high-resolution tier, at 1080p and 4K.", "default": "standard" } }, "required": [ "aspect_ratio", "duration_ms" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "duration_ms", "resolution", "start_image" ], "properties": { "quality": { "enum": [ "pro" ] }, "resolution": { "enum": [ "1080p", "4K" ] } } }, { "required": [ "aspect_ratio", "duration_ms", "images", "resolution" ], "properties": { "quality": { "enum": [ "pro" ] }, "resolution": { "enum": [ "1080p", "4K" ] } } }, { "required": [ "aspect_ratio", "duration_ms", "resolution" ], "properties": { "end_image": false, "images": false, "quality": { "enum": [ "pro" ] }, "resolution": { "enum": [ "1080p", "4K" ] }, "start_image": false } }, { "required": [ "aspect_ratio", "duration_ms", "start_image" ], "properties": { "quality": { "enum": [ "standard" ] }, "resolution": { "enum": [ "720p" ] } } }, { "required": [ "aspect_ratio", "duration_ms", "images" ], "properties": { "quality": { "enum": [ "standard" ] }, "resolution": { "enum": [ "720p" ] } } }, { "required": [ "aspect_ratio", "duration_ms" ], "properties": { "end_image": false, "images": false, "quality": { "enum": [ "standard" ] }, "resolution": { "enum": [ "720p" ] }, "start_image": false } } ] }, "SubmitBody_kling_o3": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_kling_o3" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_kling_o3_edit": { "description": "Model-specific inputs for `kling-o3-edit`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 2500 characters.", "maxLength": 2500, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Source video. From 3s to 15s and at most 524.2 MB.", "media_type": "video", "role": "input_video", "min_duration_ms": 3000, "max_duration_ms": 15000, "max_file_size_bytes": 524288000 }, "images": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 4, "minItems": 1, "type": "array", "description": "Reference images. 1 to 4 images, each at least 300px on each side and at most 10.4 MB.", "media_type": "image", "role": "reference", "min_dimension_px": 300, "max_file_size_bytes": 10485760 }, "resolution": { "type": "string", "enum": [ "720p", "1080p", "4K" ], "description": "Output resolution to generate at." } }, "required": [ "prompt", "resolution", "source_video" ], "additionalProperties": false }, "SubmitBody_kling_o3_edit": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_kling_o3_edit" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_kling_o3_reference": { "description": "Model-specific inputs for `kling-o3-reference`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 2500 characters.", "maxLength": 2500, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Source video. From 3s to 15s and at most 524.2 MB.", "media_type": "video", "role": "input_video", "min_duration_ms": 3000, "max_duration_ms": 15000, "max_file_size_bytes": 524288000 }, "images": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 4, "minItems": 1, "type": "array", "description": "Reference images. 1 to 4 images, each at least 300px on each side and at most 10.4 MB.", "media_type": "image", "role": "reference", "min_dimension_px": 300, "max_file_size_bytes": 10485760 }, "resolution": { "type": "string", "enum": [ "720p", "1080p" ], "description": "Output resolution to generate at." } }, "required": [ "prompt", "resolution", "source_video" ], "additionalProperties": false }, "SubmitBody_kling_o3_reference": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_kling_o3_reference" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_kling_v3": { "description": "Model-specific inputs for `kling-v3`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "maxLength": 2500, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string", "description": "Generation prompt. At most 2500 characters." }, "multi_prompt": { "items": { "additionalProperties": false, "description": "One shot of a published multi-shot storyboard.", "properties": { "prompt": { "description": "The prompt for this shot.", "type": "string" }, "duration_ms": { "default": 5000, "description": "Duration of this shot in milliseconds.", "enum": [ 1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000 ], "type": "integer" } }, "required": [ "prompt" ], "type": "object" }, "maxItems": 6, "minItems": 1, "type": "array", "description": "Multi-shot storyboard; each shot carries its own prompt and duration. Shot durations must sum to at most 15000 ms, and the storyboard replaces `prompt` \u2014 supply one or the other, never both. A shot's prompt has no length limit, unlike the single `prompt` field. 1 to 6 items." }, "shot_type": { "enum": [ "customize", "intelligent" ], "type": "string", "description": "How a multi-shot storyboard is cut. 'customize' honours each shot's declared duration; 'intelligent' lets the model determine the shot structure. Ignored unless `multi_prompt` is supplied." }, "generate_audio": { "default": true, "description": "Whether to generate native audio for the video.", "type": "boolean" }, "negative_prompt": { "maxLength": 2500, "type": "string", "description": "What to avoid in the generated video. At most 2500 characters." }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "1080p", "4K", "720p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000 ], "type": "integer" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "cfg_scale": { "maximum": 1.0, "minimum": 0.0, "type": "number", "description": "How closely the model follows the prompt. From 0 to 1." }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. At most 10.4 MB.", "media_type": "image", "role": "end_frame", "max_file_size_bytes": 10485760 }, "quality": { "type": "string", "enum": [ "standard", "pro" ], "description": "Quality level to generate at. `standard` \u2014 the 720p tier. `pro` \u2014 the high-resolution tier, at 1080p and 4K.", "default": "standard" } }, "required": [ "aspect_ratio", "duration_ms" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "duration_ms", "resolution", "start_image" ], "properties": { "end_image": false, "quality": { "enum": [ "pro" ] }, "resolution": { "enum": [ "1080p", "4K" ] } } }, { "required": [ "aspect_ratio", "duration_ms", "end_image", "resolution", "start_image" ], "properties": { "quality": { "enum": [ "pro" ] }, "resolution": { "enum": [ "1080p", "4K" ] } } }, { "required": [ "aspect_ratio", "duration_ms", "resolution" ], "properties": { "end_image": false, "quality": { "enum": [ "pro" ] }, "resolution": { "enum": [ "1080p", "4K" ] }, "start_image": false } }, { "required": [ "aspect_ratio", "duration_ms", "start_image" ], "properties": { "end_image": false, "quality": { "enum": [ "standard" ] }, "resolution": { "enum": [ "720p" ] } } }, { "required": [ "aspect_ratio", "duration_ms", "end_image", "start_image" ], "properties": { "quality": { "enum": [ "standard" ] }, "resolution": { "enum": [ "720p" ] } } }, { "required": [ "aspect_ratio", "duration_ms" ], "properties": { "end_image": false, "quality": { "enum": [ "standard" ] }, "resolution": { "enum": [ "720p" ] }, "start_image": false } } ] }, "SubmitBody_kling_v3": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_kling_v3" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_kling_v3_motion_control": { "description": "Model-specific inputs for `kling-v3-motion-control`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "maxLength": 2500, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string", "description": "Generation prompt. At most 2500 characters." }, "character_orientation": { "default": "video", "description": "Whether the output character's orientation follows the reference video ('video' \u2014 better for complex motion) or the character image ('image' \u2014 better for camera movement). Also caps the source video: 30s for 'video', 10s for 'image'.", "enum": [ "image", "video" ], "type": "string" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. From 340px to 3850px on each side and at most 10.4 MB.", "media_type": "image", "role": "start_frame", "min_dimension_px": 340, "max_file_size_bytes": 10485760, "max_dimension_px": 3850 }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Source video. From 3s to 30s, from 340px to 3850px on each side, and at most 104.8 MB.", "media_type": "video", "role": "input_video", "min_dimension_px": 340, "min_duration_ms": 3000, "max_file_size_bytes": 104857600, "max_dimension_px": 3850, "max_duration_ms": 30000 }, "resolution": { "type": "string", "enum": [ "720p", "1080p" ], "description": "Output resolution to generate at." } }, "required": [ "resolution", "source_video", "start_image" ], "additionalProperties": false }, "SubmitBody_kling_v3_motion_control": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_kling_v3_motion_control" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_krea_2": { "description": "Model-specific inputs for `krea-2`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt. From 1 to 5000 characters.", "maxLength": 5000, "minLength": 1, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "4:3", "3:2", "16:9", "2.35:1", "4:5", "2:3", "9:16" ], "type": "string" }, "creativity": { "enum": [ "raw", "low", "medium", "high" ], "type": "string", "description": "How loosely the model may read the prompt. 'raw' stays closest to it; 'high' drifts furthest for a more inventive result. Omit for Krea's own default ('medium')." }, "images": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 10, "minItems": 1, "type": "array", "description": "Reference images whose style \u2014 palette, lighting, texture, art direction \u2014 the generated image takes on. A reference with no clear subject of its own can crowd out the one you prompted for; lower `style_strength` to hold it back. Omit them to render from the prompt alone. 1 to 10 images, each at most 30 MB.", "media_type": "image", "role": "reference", "max_file_size_bytes": 30000000 }, "style_strength": { "maximum": 1.0, "minimum": 0.0, "type": "number", "description": "How strongly the reference images pull the render toward their style, applied to every one of them. Krea pulls as hard as it can unless you say otherwise; lower this to leave more of the prompt's own subject, and 0 to ignore the references' style entirely. From 0 to 1." }, "seed": { "type": "integer", "description": "Seed passed to Krea. It does not make a render repeatable \u2014 Krea returns a different image each time from the same seed." }, "quality": { "type": "string", "enum": [ "medium", "large" ], "description": "Quality level to generate at. `medium` \u2014 the smaller model, strongest on illustration, anime and painting. `large` \u2014 the larger model, for photorealism and the effects that sell it \u2014 motion blur, grain, low dynamic range.", "default": "medium" } }, "required": [ "aspect_ratio", "prompt" ], "additionalProperties": false }, "SubmitBody_krea_2": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_krea_2" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_ltx_2_3": { "description": "Model-specific inputs for `ltx-2-3`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. From 1 to 5000 characters.", "maxLength": 5000, "minLength": 1, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "1080p", "1440p", "2160p" ], "type": "string" }, "generate_audio": { "default": true, "description": "Whether to generate native audio for the video.", "type": "boolean" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 6000, 8000, 10000, 12000, 14000, 16000, 18000, 20000 ], "type": "integer" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "auto", "16:9", "9:16" ], "type": "string" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. At most 10.4 MB.", "media_type": "image", "role": "end_frame", "max_file_size_bytes": 10485760 }, "quality": { "type": "string", "enum": [ "fast", "pro" ], "description": "Quality level to generate at. `fast` \u2014 tuned for turnaround, for iteration. `pro` \u2014 the higher-fidelity tier, for final output.", "default": "pro" } }, "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution", "start_image" ], "properties": { "quality": { "enum": [ "fast" ] } } }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "properties": { "aspect_ratio": { "enum": [ "16:9", "9:16" ] }, "end_image": false, "quality": { "enum": [ "fast" ] }, "start_image": false } }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution", "start_image" ], "properties": { "duration_ms": { "enum": [ 6000, 8000, 10000 ] }, "quality": { "enum": [ "pro" ] } } }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "properties": { "aspect_ratio": { "enum": [ "16:9", "9:16" ] }, "duration_ms": { "enum": [ 6000, 8000, 10000 ] }, "end_image": false, "quality": { "enum": [ "pro" ] }, "start_image": false } } ] }, "SubmitBody_ltx_2_3": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_ltx_2_3" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_ltx_2_5": { "description": "Model-specific inputs for `ltx-2-5`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. From 1 to 5000 characters.", "maxLength": 5000, "minLength": 1, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "1080p", "720p", "1440p", "2160p" ] }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "auto", "16:9", "9:16" ], "type": "string" }, "audio": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Driving audio. From 2s to 20s and at most 104.8 MB.", "media_type": "audio", "role": "audio_input", "min_duration_ms": 2000, "max_duration_ms": 20000, "max_file_size_bytes": 104857600 }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "generate_audio": { "default": true, "description": "Whether to generate native audio for the video.", "type": "boolean" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 6000, 8000, 10000, 12000, 14000, 16000, 18000, 20000 ], "type": "integer" }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. At most 10.4 MB.", "media_type": "image", "role": "end_frame", "max_file_size_bytes": 10485760 }, "quality": { "type": "string", "enum": [ "fast", "pro" ], "description": "Quality level to generate at. `fast` \u2014 tuned for turnaround, and the only level that renders 1440p, 2160p, or clips past 10 seconds. `pro` \u2014 the higher-fidelity tier, for final output at 720p or 1080p, and the level that caps both the clip it renders and the audio driving it at 10 seconds.", "default": "fast" } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "audio", "prompt" ], "properties": { "duration_ms": false, "end_image": false, "generate_audio": false, "resolution": { "enum": [ "1080p" ] } } }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution", "start_image" ], "properties": { "audio": false, "quality": { "enum": [ "fast" ] } } }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "properties": { "aspect_ratio": { "enum": [ "16:9", "9:16" ] }, "audio": false, "end_image": false, "quality": { "enum": [ "fast" ] }, "start_image": false } }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution", "start_image" ], "properties": { "audio": false, "duration_ms": { "enum": [ 6000, 8000, 10000 ] }, "quality": { "enum": [ "pro" ] }, "resolution": { "enum": [ "1080p", "720p" ] } } }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "properties": { "aspect_ratio": { "enum": [ "16:9", "9:16" ] }, "audio": false, "duration_ms": { "enum": [ 6000, 8000, 10000 ] }, "end_image": false, "quality": { "enum": [ "pro" ] }, "resolution": { "enum": [ "1080p", "720p" ] }, "start_image": false } } ] }, "SubmitBody_ltx_2_5": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_ltx_2_5" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_luma_ray_32": { "description": "Model-specific inputs for `luma-ray-32`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 6000 characters.", "maxLength": 6000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "3:4", "4:3", "1:1", "9:16", "16:9", "21:9" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "540p", "720p", "1080p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 5000, 10000 ], "type": "integer" } }, "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_luma_ray_32": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_luma_ray_32" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_mai_image_2_5": { "description": "Model-specific inputs for `mai-image-2-5`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt. From 3 to 5000 characters.", "maxLength": 5000, "minLength": 3, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "4:3", "3:4", "16:9", "9:16", "3:2", "2:3" ], "type": "string" }, "images": { "description": "The single source image to edit. Exactly 1 image, at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 1, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "output_format": { "enum": [ "jpeg", "png", "webp" ], "type": "string", "description": "Output image format." }, "quality": { "type": "string", "enum": [ "standard", "pro" ], "description": "Quality level to generate at. `standard` \u2014 photorealistic generation and editing at the base rate. `pro` \u2014 the higher-fidelity tier, for final deliverables that need maximum detail and text rendering.", "default": "standard" } }, "required": [ "aspect_ratio", "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "images", "prompt" ] }, { "required": [ "aspect_ratio", "prompt" ], "properties": { "images": false } } ] }, "SubmitBody_mai_image_2_5": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_mai_image_2_5" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_minimax_h3": { "description": "Model-specific inputs for `minimax-h3`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. From 1 to 7000 characters.", "maxLength": 7000, "minLength": 1, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "480p", "768p", "2K", "4K" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000 ], "type": "integer" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. From 256px to 5760px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "media_type": "image", "role": "start_frame", "min_dimension_px": 256, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 5760, "max_aspect_ratio": 2.5 }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. From 256px to 5760px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "media_type": "image", "role": "end_frame", "min_dimension_px": 256, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 5760, "max_aspect_ratio": 2.5 }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "3:4", "4:3", "16:9", "21:9", "9:16", "adaptive" ], "type": "string" }, "images": { "description": "Reference images. 1 to 5 images, each from 256px to 5760px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 5, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "min_dimension_px": 256, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 5760, "max_aspect_ratio": 2.5 }, "videos": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 3, "minItems": 1, "type": "array", "description": "Reference videos. 1 to 3 videos, each from 2s to 15s and at most 524.2 MB, at most 15s in total.", "media_type": "video", "role": "reference", "min_duration_ms": 2000, "max_duration_ms": 15000, "max_total_duration_ms": 15000, "max_file_size_bytes": 524288000 }, "audios": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 3, "minItems": 1, "type": "array", "description": "Reference audios. 1 to 3 audio files, each from 2s to 15s and at most 104.8 MB, at most 15s in total.", "media_type": "audio", "role": "reference", "min_duration_ms": 2000, "max_duration_ms": 15000, "max_total_duration_ms": 15000, "max_file_size_bytes": 104857600 } }, "required": [ "duration_ms", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "duration_ms", "prompt", "resolution", "start_image" ], "properties": { "aspect_ratio": false, "audios": false, "end_image": false, "images": false, "videos": false } }, { "required": [ "duration_ms", "end_image", "prompt", "resolution", "start_image" ], "properties": { "aspect_ratio": false, "audios": false, "images": false, "videos": false } }, { "required": [ "aspect_ratio", "duration_ms", "images", "prompt", "resolution" ], "properties": { "end_image": false, "start_image": false } }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "properties": { "aspect_ratio": { "enum": [ "1:1", "3:4", "4:3", "16:9", "21:9", "9:16" ] }, "audios": false, "end_image": false, "images": false, "start_image": false, "videos": false } } ] }, "SubmitBody_minimax_h3": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_minimax_h3" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_minimax_h3_max_camera_controls": { "description": "Model-specific inputs for `minimax-h3-max-camera-controls`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. From 1 to 7000 characters.", "maxLength": 7000, "minLength": 1, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "480p", "768p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000 ], "type": "integer" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. From 256px to 5760px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "media_type": "image", "role": "start_frame", "min_dimension_px": 256, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 5760, "max_aspect_ratio": 2.5 }, "camera_trajectory": { "description": "Camera path through the scene, as poses ordered by strictly increasing `time`. The first pose holds until its `time` and the last holds to the end of the clip; the camera interpolates between them. `time` runs 0 (start) to 1 (end), `azimuth` is the horizontal angle around the subject in degrees, `elevation` the vertical angle in degrees from -90 to 90, and `distance` the distance from the subject in scene units (above 0; 1 is where the input frame sits). Consecutive azimuths may travel at most 32 full turns in total. 2 to 12 items.", "items": { "additionalProperties": false, "description": "One camera pose at a normalized point in the generated clip.", "properties": { "time": { "description": "When this pose applies, from 0 at the start to 1 at the end.", "maximum": 1.0, "minimum": 0.0, "type": "number" }, "azimuth": { "description": "Horizontal camera angle around the subject, in degrees.", "type": "number" }, "elevation": { "description": "Vertical camera angle around the subject, in degrees.", "maximum": 90.0, "minimum": -90.0, "type": "number" }, "distance": { "description": "Camera distance from the subject, in normalized scene units.", "exclusiveMinimum": 0.0, "type": "number" } }, "required": [ "time", "azimuth", "elevation", "distance" ], "type": "object" }, "maxItems": 12, "minItems": 2, "type": "array" } }, "required": [ "camera_trajectory", "duration_ms", "prompt", "resolution", "start_image" ], "additionalProperties": false }, "SubmitBody_minimax_h3_max_camera_controls": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_minimax_h3_max_camera_controls" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_minimax_h3_max_turbo": { "description": "Model-specific inputs for `minimax-h3-max-turbo`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. From 1 to 7000 characters.", "maxLength": 7000, "minLength": 1, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "480p", "768p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000 ], "type": "integer" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. From 256px to 5760px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "media_type": "image", "role": "start_frame", "min_dimension_px": 256, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 5760, "max_aspect_ratio": 2.5 }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. From 256px to 5760px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "media_type": "image", "role": "end_frame", "min_dimension_px": 256, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 5760, "max_aspect_ratio": 2.5 }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "3:4", "4:3", "1:1", "9:16", "16:9", "21:9" ], "type": "string" } }, "required": [ "duration_ms", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "duration_ms", "prompt", "resolution", "start_image" ], "properties": { "aspect_ratio": false, "end_image": false } }, { "required": [ "duration_ms", "end_image", "prompt", "resolution", "start_image" ], "properties": { "aspect_ratio": false } }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "properties": { "end_image": false, "start_image": false } } ] }, "SubmitBody_minimax_h3_max_turbo": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_minimax_h3_max_turbo" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_minimax_hailuo_02": { "description": "Model-specific inputs for `minimax-hailuo-02`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 2000 characters.", "maxLength": 2000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "1080p", "768p" ] }, "duration_ms": { "type": "integer", "description": "Duration in ms.", "enum": [ 6000, 10000 ] }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. The output video follows this image's aspect ratio. At most 20 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 20000000 }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. At most 20 MB.", "media_type": "image", "role": "end_frame", "max_file_size_bytes": 20000000 }, "aspect_ratio": { "type": "string", "description": "Output aspect ratio.", "enum": [ "16:9" ] }, "quality": { "type": "string", "enum": [ "standard", "pro" ], "description": "Quality level to generate at. `standard` \u2014 768p, for everyday motion. `pro` \u2014 1080p, with smoother motion and sharper detail.", "default": "standard" } }, "required": [ "duration_ms", "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "prompt", "start_image" ], "properties": { "aspect_ratio": false, "duration_ms": { "enum": [ 6000 ] }, "end_image": false, "quality": { "enum": [ "pro" ] }, "resolution": { "enum": [ "1080p" ] } } }, { "required": [ "end_image", "prompt", "start_image" ], "properties": { "aspect_ratio": false, "duration_ms": { "enum": [ 6000 ] }, "quality": { "enum": [ "pro" ] }, "resolution": { "enum": [ "1080p" ] } } }, { "required": [ "prompt" ], "properties": { "duration_ms": { "enum": [ 6000 ] }, "end_image": false, "quality": { "enum": [ "pro" ] }, "resolution": { "enum": [ "1080p" ] }, "start_image": false } }, { "required": [ "duration_ms", "prompt", "start_image" ], "properties": { "aspect_ratio": false, "end_image": false, "quality": { "enum": [ "standard" ] }, "resolution": { "enum": [ "768p" ] } } }, { "required": [ "duration_ms", "end_image", "prompt", "start_image" ], "properties": { "aspect_ratio": false, "quality": { "enum": [ "standard" ] }, "resolution": { "enum": [ "768p" ] } } }, { "required": [ "duration_ms", "prompt" ], "properties": { "end_image": false, "quality": { "enum": [ "standard" ] }, "resolution": { "enum": [ "768p" ] }, "start_image": false } } ] }, "SubmitBody_minimax_hailuo_02": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_minimax_hailuo_02" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_minimax_hailuo_23": { "description": "Model-specific inputs for `minimax-hailuo-23`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 2000 characters.", "maxLength": 2000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "1080p", "768p" ] }, "duration_ms": { "type": "integer", "description": "Duration in ms.", "enum": [ 6000, 10000 ] }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. The output video follows this image's aspect ratio. At most 20 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 20000000 }, "aspect_ratio": { "type": "string", "description": "Output aspect ratio.", "enum": [ "16:9" ] }, "quality": { "type": "string", "enum": [ "standard", "pro", "fast-standard", "fast-pro" ], "description": "Quality level to generate at. `standard` \u2014 768p, for everyday motion. `pro` \u2014 1080p, with smoother motion and sharper detail. `fast-standard` \u2014 768p on the low-latency path, from a start frame only. `fast-pro` \u2014 1080p on the low-latency path, from a start frame only.", "default": "standard" } }, "required": [ "duration_ms", "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "prompt", "start_image" ], "properties": { "aspect_ratio": false, "duration_ms": { "enum": [ 6000 ] }, "quality": { "enum": [ "pro", "fast-pro" ] }, "resolution": { "enum": [ "1080p" ] } } }, { "required": [ "duration_ms", "prompt", "start_image" ], "properties": { "aspect_ratio": false, "quality": { "enum": [ "standard", "fast-standard" ] }, "resolution": { "enum": [ "768p" ] } } }, { "required": [ "prompt" ], "properties": { "duration_ms": { "enum": [ 6000 ] }, "quality": { "enum": [ "pro" ] }, "resolution": { "enum": [ "1080p" ] }, "start_image": false } }, { "required": [ "duration_ms", "prompt" ], "properties": { "quality": { "enum": [ "standard" ] }, "resolution": { "enum": [ "768p" ] }, "start_image": false } } ] }, "SubmitBody_minimax_hailuo_23": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_minimax_hailuo_23" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_minimax_speech_25_hd_preview": { "description": "Model-specific inputs for `minimax-speech-25-hd-preview`.", "type": "object", "properties": { "text": { "description": "Generation prompt. At most 9999 characters.", "maxLength": 9999, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "stability": { "default": 1.0, "description": "Voice stability. Higher values give a steadier, more consistent delivery; lower values allow more expressive variation between generations. From 0 to 1.", "maximum": 1.0, "minimum": 0.0, "type": "number" }, "speed": { "default": 1.0, "description": "Speech rate multiplier; 1.0 is the voice's natural pace. From 0.7 to 1.2.", "maximum": 1.2, "minimum": 0.7, "type": "number" }, "language": { "type": "string", "description": "Language code; 'auto' by default." }, "voice_id": { "description": "Voice to speak with (`voice_`). List the voices you can use at GET /v3/models/minimax-speech-25-hd-preview/voices.", "type": "string" } }, "required": [ "text", "voice_id" ], "additionalProperties": false }, "SubmitBody_minimax_speech_25_hd_preview": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_minimax_speech_25_hd_preview" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_minimax_speech_25_turbo_preview": { "description": "Model-specific inputs for `minimax-speech-25-turbo-preview`.", "type": "object", "properties": { "text": { "description": "Generation prompt. At most 9999 characters.", "maxLength": 9999, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "stability": { "default": 1.0, "description": "Voice stability. Higher values give a steadier, more consistent delivery; lower values allow more expressive variation between generations. From 0 to 1.", "maximum": 1.0, "minimum": 0.0, "type": "number" }, "speed": { "default": 1.0, "description": "Speech rate multiplier; 1.0 is the voice's natural pace. From 0.7 to 1.2.", "maximum": 1.2, "minimum": 0.7, "type": "number" }, "language": { "type": "string", "description": "Language code; 'auto' by default." }, "voice_id": { "description": "Voice to speak with (`voice_`). List the voices you can use at GET /v3/models/minimax-speech-25-turbo-preview/voices.", "type": "string" } }, "required": [ "text", "voice_id" ], "additionalProperties": false }, "SubmitBody_minimax_speech_25_turbo_preview": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_minimax_speech_25_turbo_preview" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_muse_image": { "description": "Model-specific inputs for `muse-image`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "adaptive", "21:9", "16:9", "3:2", "4:3", "1:1", "3:4", "2:3", "9:16", "9:21" ], "type": "string" }, "images": { "description": "Images to edit or blend. 1 to 10 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 10, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "output_format": { "enum": [ "jpeg", "png", "webp" ], "type": "string", "description": "Output image format." } }, "required": [ "aspect_ratio", "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "images", "prompt" ] }, { "required": [ "aspect_ratio", "prompt" ], "properties": { "images": false } } ] }, "SubmitBody_muse_image": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_muse_image" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_nano_banana": { "description": "Model-specific inputs for `nano-banana`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1" ], "type": "string" }, "resolution": { "description": "Accepted and ignored. gemini-2.5-flash-image takes no `image_size` argument \u2014 the aspect ratio alone decides the output geometry \u2014 so this value never reaches the provider and never changes the price. It stays on the contract because requests already send it.", "enum": [ "1K", "2K", "4K" ], "type": "string" }, "images": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 3, "minItems": 1, "type": "array", "description": "Images to edit or blend. 1 to 3 images, each at most 30 MB.", "media_type": "image", "role": "reference", "max_file_size_bytes": 30000000 }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_nano_banana": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_nano_banana" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_nano_banana_2": { "description": "Model-specific inputs for `nano-banana-2`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio. 'adaptive' lets the model size the output itself \u2014 matching the source image when you pass one.", "enum": [ "adaptive", "16:9", "9:16", "1:1", "21:9", "4:3", "3:4", "3:2", "2:3", "5:4", "4:5", "1:4", "4:1", "1:8", "8:1" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "512px", "1K", "2K", "4K" ], "type": "string" }, "images": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 14, "minItems": 1, "type": "array", "description": "Images to edit or blend, at most 10 high-fidelity objects and 4 characters. 1 to 14 images, each at most 30 MB.", "media_type": "image", "role": "reference", "max_file_size_bytes": 30000000 }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." }, "google_search": { "default": false, "description": "Ground the generation in live Google Search results, so a prompt about current events or real-world specifics draws on what the web says now. Grounded generations cost more than ungrounded ones.", "type": "boolean" }, "image_search": { "default": false, "description": "Let the grounding search return images as well as text, so the model sees what it found rather than only reading about it. Turning this on grounds the generation whether or not google_search is also set.", "type": "boolean" }, "thinking_level": { "enum": [ "minimal", "high" ], "type": "string", "description": "How much the model plans before it draws. Omit for the model's own default ('minimal'); 'high' reasons further at the cost of latency." } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_nano_banana_2": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_nano_banana_2" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_nano_banana_pro": { "description": "Model-specific inputs for `nano-banana-pro`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio. 'adaptive' lets the model size the output itself \u2014 matching the source image when you pass one.", "enum": [ "adaptive", "16:9", "9:16", "1:1", "21:9", "4:3", "3:4", "3:2", "2:3", "5:4", "4:5" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "1K", "2K", "4K" ], "type": "string" }, "images": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 14, "minItems": 1, "type": "array", "description": "Images to edit or blend, at most 6 high-fidelity objects, 5 characters and 3 style references. 1 to 14 images, each at most 30 MB.", "media_type": "image", "role": "reference", "max_file_size_bytes": 30000000 }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." }, "google_search": { "default": false, "description": "Ground the generation in live Google Search results, so a prompt about current events or real-world specifics draws on what the web says now. Grounded generations cost more than ungrounded ones.", "type": "boolean" } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_nano_banana_pro": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_nano_banana_pro" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_omnihuman_15": { "description": "Model-specific inputs for `omnihuman-15`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "pattern": "[^\\s\\x1C-\\x1F]", "type": "string", "description": "Generation prompt." }, "aspect_ratio": { "type": "string", "description": "Output aspect ratio.", "enum": [ "16:9" ] }, "resolution": { "description": "Output resolution.", "enum": [ "720p", "1080p" ], "type": "string" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "audio": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Driving audio. At most 59.88s and at most 104.8 MB.", "media_type": "audio", "role": "audio_input", "max_duration_ms": 59880, "max_file_size_bytes": 104857600 } }, "required": [ "audio", "resolution", "start_image" ], "additionalProperties": false }, "SubmitBody_omnihuman_15": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_omnihuman_15" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_pixverse_v6": { "description": "Model-specific inputs for `pixverse-v6`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 2048 characters.", "maxLength": 2048, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "360p", "540p", "720p", "1080p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000 ], "type": "integer" }, "generate_audio": { "default": true, "description": "Whether to generate native audio for the video.", "type": "boolean" }, "negative_prompt": { "maxLength": 2048, "type": "string", "description": "What to avoid in the generated video. At most 2048 characters." }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "4:3", "1:1", "3:4", "9:16", "2:3", "3:2", "21:9" ], "type": "string" } }, "required": [ "duration_ms", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "duration_ms", "prompt", "resolution", "start_image" ], "properties": { "aspect_ratio": false } }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "properties": { "start_image": false } } ] }, "SubmitBody_pixverse_v6": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_pixverse_v6" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_qwen_image_2": { "description": "Model-specific inputs for `qwen-image-2`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt. At least 1 character.", "minLength": 1, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "540p", "720p", "1080p", "1440p (2K QHD)" ], "type": "string" }, "output_format": { "enum": [ "jpeg", "png", "webp" ], "type": "string", "description": "Output image format." }, "negative_prompt": { "maxLength": 500, "type": "string", "description": "What to avoid in the generated image. At most 500 characters." }, "images": { "description": "Images to edit or blend. 1 to 3 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 3, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "seed": { "maximum": 2147483647, "minimum": 0, "type": "integer", "description": "Seed for reproducible output; omit for a random seed. From 0 to 2147483647." }, "quality": { "type": "string", "enum": [ "standard", "pro" ], "description": "Quality level to generate at. `standard` \u2014 tuned for speed, for rapid iteration. `pro` \u2014 the higher-fidelity tier, for fine detail and in-image text accuracy.", "default": "standard" } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "images", "prompt", "resolution" ] }, { "required": [ "aspect_ratio", "prompt", "resolution" ], "properties": { "images": false } } ] }, "SubmitBody_qwen_image_2": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_qwen_image_2" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_recraft_v3": { "description": "Model-specific inputs for `recraft-v3`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt. At most 1000 characters.", "maxLength": 1000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "1:3", "2:3", "3:1", "3:2", "3:4", "4:3", "16:9", "9:16", "10:16", "16:10" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "540p", "720p", "1080p", "1440p (2K QHD)", "2160p (4K UHD)" ], "type": "string" } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_recraft_v3": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_recraft_v3" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_reve_21": { "description": "Model-specific inputs for `reve-21`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt. From 1 to 4000 characters.", "maxLength": 4000, "minLength": 1, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "4:1", "3:1", "21:9", "2:1", "17:9", "16:9", "3:2", "4:3", "5:4", "1:1", "4:5", "3:4", "2:3", "9:16", "1:2", "1:3", "1:4" ], "type": "string" }, "output_format": { "enum": [ "jpeg", "png", "webp" ], "type": "string", "description": "Output image format." } }, "required": [ "aspect_ratio", "prompt" ], "additionalProperties": false }, "SubmitBody_reve_21": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_reve_21" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_reve_21_edit": { "description": "Model-specific inputs for `reve-21-edit`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt. From 1 to 4000 characters.", "maxLength": 4000, "minLength": 1, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "4:1", "3:1", "21:9", "2:1", "17:9", "16:9", "3:2", "4:3", "5:4", "1:1", "4:5", "3:4", "2:3", "9:16", "1:2", "1:3", "1:4" ], "type": "string" }, "images": { "description": "The single source image to edit. Exactly 1 image, at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 1, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "output_format": { "enum": [ "jpeg", "png", "webp" ], "type": "string", "description": "Output image format." } }, "required": [ "aspect_ratio", "images", "prompt" ], "additionalProperties": false }, "SubmitBody_reve_21_edit": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_reve_21_edit" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_reve_21_remix": { "description": "Model-specific inputs for `reve-21-remix`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt. From 1 to 4000 characters.", "maxLength": 4000, "minLength": 1, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "4:1", "3:1", "21:9", "2:1", "17:9", "16:9", "3:2", "4:3", "5:4", "1:1", "4:5", "3:4", "2:3", "9:16", "1:2", "1:3", "1:4" ], "type": "string" }, "images": { "description": "Images to edit or blend. 1 to 8 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 8, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 }, "output_format": { "enum": [ "jpeg", "png", "webp" ], "type": "string", "description": "Output image format." } }, "required": [ "aspect_ratio", "images", "prompt" ], "additionalProperties": false }, "SubmitBody_reve_21_remix": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_reve_21_remix" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_sana": { "description": "Model-specific inputs for `sana`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "1:3", "2:3", "3:1", "3:2", "3:4", "4:3", "16:9", "9:16", "10:16", "16:10" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "540p", "720p", "1080p", "1440p (2K QHD)", "2160p (4K UHD)" ], "type": "string" }, "output_format": { "enum": [ "jpeg", "png" ], "type": "string", "description": "Output image format." }, "negative_prompt": { "type": "string", "description": "What to avoid in the generated image." }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." }, "guidance_scale": { "maximum": 20.0, "minimum": 0.0, "type": "number", "description": "How closely the model follows the prompt. From 0 to 20." }, "num_inference_steps": { "maximum": 50, "minimum": 1, "type": "integer", "description": "Denoising steps to run. From 1 to 50." } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_sana": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_sana" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_seedance_15_pro": { "description": "Model-specific inputs for `seedance-15-pro`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "3:4", "4:3", "16:9", "21:9", "9:16", "adaptive" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "480p", "720p", "1080p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 4000, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000 ], "type": "integer" }, "generate_audio": { "default": true, "description": "Whether to generate native audio for the video.", "type": "boolean" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. From 300px to 6000px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "media_type": "image", "role": "start_frame", "min_dimension_px": 300, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 6000, "max_aspect_ratio": 2.5 }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. From 300px to 6000px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "media_type": "image", "role": "end_frame", "min_dimension_px": 300, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 6000, "max_aspect_ratio": 2.5 }, "seed": { "maximum": 4294967295, "minimum": 0, "type": "integer", "description": "Seed for reproducible output; omit for a random seed. From 0 to 4294967295." } }, "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_seedance_15_pro": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_seedance_15_pro" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_seedance_20": { "description": "Model-specific inputs for `seedance-20`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "3:4", "4:3", "16:9", "21:9", "9:16", "adaptive" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "4K", "480p", "720p", "1080p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 4000, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000 ], "type": "integer" }, "generate_audio": { "default": true, "description": "Whether to generate native audio for the video.", "type": "boolean" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. From 300px to 6000px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "media_type": "image", "role": "start_frame", "min_dimension_px": 300, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 6000, "max_aspect_ratio": 2.5 }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. From 300px to 6000px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "media_type": "image", "role": "end_frame", "min_dimension_px": 300, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 6000, "max_aspect_ratio": 2.5 }, "images": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 9, "minItems": 1, "type": "array", "description": "Reference images. 1 to 9 images, each from 300px to 6000px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "media_type": "image", "role": "reference", "min_dimension_px": 300, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 6000, "max_aspect_ratio": 2.5 }, "videos": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 3, "minItems": 1, "type": "array", "description": "Reference videos. 1 to 3 videos, each from 2s to 15.15s and at most 524.2 MB, at most 15.15s in total.", "media_type": "video", "role": "reference", "min_duration_ms": 2000, "max_duration_ms": 15150, "max_total_duration_ms": 15150, "max_file_size_bytes": 524288000 }, "audios": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 3, "minItems": 1, "type": "array", "description": "Reference audios. 1 to 3 audio files, each at most 104.8 MB, at most 15.15s in total.", "media_type": "audio", "role": "reference", "max_total_duration_ms": 15150, "max_file_size_bytes": 104857600 }, "quality": { "type": "string", "enum": [ "standard", "fast" ], "description": "Quality level to generate at. `standard` \u2014 the full model, and the only level that reaches 1080p and 4K. `fast` \u2014 tuned for turnaround, at 480p and 720p.", "default": "standard" } }, "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "properties": { "quality": { "enum": [ "standard" ] } } }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "properties": { "quality": { "enum": [ "fast" ] }, "resolution": { "enum": [ "480p", "720p" ] } } } ] }, "SubmitBody_seedance_20": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_seedance_20" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_seedance_20_mini": { "description": "Model-specific inputs for `seedance-20-mini`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "3:4", "4:3", "16:9", "21:9", "9:16", "adaptive" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "480p", "720p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 4000, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000 ], "type": "integer" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. From 300px to 6000px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "media_type": "image", "role": "start_frame", "min_dimension_px": 300, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 6000, "max_aspect_ratio": 2.5 }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. From 300px to 6000px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "media_type": "image", "role": "end_frame", "min_dimension_px": 300, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 6000, "max_aspect_ratio": 2.5 }, "images": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 9, "minItems": 1, "type": "array", "description": "Reference images. 1 to 9 images, each from 300px to 6000px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "media_type": "image", "role": "reference", "min_dimension_px": 300, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 6000, "max_aspect_ratio": 2.5 }, "videos": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 3, "minItems": 1, "type": "array", "description": "Reference videos. 1 to 3 videos, each from 2s to 15.15s and at most 524.2 MB, at most 15.15s in total.", "media_type": "video", "role": "reference", "min_duration_ms": 2000, "max_duration_ms": 15150, "max_total_duration_ms": 15150, "max_file_size_bytes": 524288000 }, "audios": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 3, "minItems": 1, "type": "array", "description": "Reference audios. 1 to 3 audio files, each at most 104.8 MB, at most 15.15s in total.", "media_type": "audio", "role": "reference", "max_total_duration_ms": 15150, "max_file_size_bytes": 104857600 } }, "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_seedance_20_mini": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_seedance_20_mini" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_seedance_25": { "description": "Model-specific inputs for `seedance-25`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "3:4", "4:3", "16:9", "21:9", "9:16", "adaptive" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "480p", "720p", "1080p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ -1, 4000, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000, 16000, 17000, 18000, 19000, 20000, 21000, 22000, 23000, 24000, 25000, 26000, 27000, 28000, 29000, 30000 ], "type": "integer" }, "generate_audio": { "default": true, "description": "Whether to generate native audio for the video.", "type": "boolean" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. From 300px to 6000px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "media_type": "image", "role": "start_frame", "min_dimension_px": 300, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 6000, "max_aspect_ratio": 2.5 }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. From 300px to 6000px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "media_type": "image", "role": "end_frame", "min_dimension_px": 300, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 6000, "max_aspect_ratio": 2.5 }, "images": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 30, "minItems": 1, "type": "array", "description": "Reference images. 1 to 30 images, each from 300px to 6000px on each side, with an aspect ratio from 0.4 to 2.5, and at most 30 MB.", "media_type": "image", "role": "reference", "min_dimension_px": 300, "min_aspect_ratio": 0.4, "max_file_size_bytes": 30000000, "max_dimension_px": 6000, "max_aspect_ratio": 2.5 }, "videos": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 10, "minItems": 1, "type": "array", "description": "Reference videos. 1 to 10 videos, each from 2s to 30.15s and at most 524.2 MB, at most 30.15s in total.", "media_type": "video", "role": "reference", "min_duration_ms": 2000, "max_duration_ms": 30150, "max_total_duration_ms": 30150, "max_file_size_bytes": 524288000 }, "audios": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 10, "minItems": 1, "type": "array", "description": "Reference audios. 1 to 10 audio files, each at most 104.8 MB, at most 30.15s in total.", "media_type": "audio", "role": "reference", "max_total_duration_ms": 30150, "max_file_size_bytes": 104857600 } }, "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_seedance_25": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_seedance_25" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_seedream_40": { "description": "Model-specific inputs for `seedream-40`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "1:3", "2:3", "3:1", "3:2", "3:4", "4:3", "16:9", "9:16", "10:16", "16:10" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "1080p", "1440p (2K QHD)", "2160p (4K UHD)" ], "type": "string" }, "images": { "description": "Images to edit or blend. 1 to 14 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 14, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "images", "prompt", "resolution" ] }, { "required": [ "aspect_ratio", "prompt", "resolution" ], "properties": { "images": false } } ] }, "SubmitBody_seedream_40": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_seedream_40" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_seedream_45": { "description": "Model-specific inputs for `seedream-45`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "1:3", "2:3", "3:1", "3:2", "3:4", "4:3", "16:9", "9:16", "10:16", "16:10" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "1440p (2K QHD)", "2160p (4K UHD)" ], "type": "string" }, "images": { "description": "Images to edit or blend. 1 to 14 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 14, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "images", "prompt", "resolution" ] }, { "required": [ "aspect_ratio", "prompt", "resolution" ], "properties": { "images": false } } ] }, "SubmitBody_seedream_45": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_seedream_45" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_seedream_50_lite": { "description": "Model-specific inputs for `seedream-50-lite`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "1:3", "2:3", "3:1", "3:2", "3:4", "4:3", "16:9", "9:16", "10:16", "16:10" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "1440p (2K QHD)", "2160p (4K UHD)" ], "type": "string" }, "output_format": { "enum": [ "jpeg", "png" ], "type": "string", "description": "Output image format." }, "images": { "description": "Images to edit or blend. 1 to 14 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 14, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "images", "prompt", "resolution" ] }, { "required": [ "aspect_ratio", "prompt", "resolution" ], "properties": { "images": false } } ] }, "SubmitBody_seedream_50_lite": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_seedream_50_lite" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_seedream_50_pro": { "description": "Model-specific inputs for `seedream-50-pro`.", "type": "object", "properties": { "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "enhance_prompt": { "default": false, "description": "Rewrite the prompt before generation. An LLM expands it into a fuller description and the model receives that text instead of the submitted one; the result's `prompt` reports what ran.", "type": "boolean" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "1:1", "1:3", "2:3", "3:1", "3:2", "3:4", "4:3", "16:9", "9:16", "10:16", "16:10" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "1080p", "1440p (2K QHD)" ], "type": "string" }, "output_format": { "enum": [ "jpeg", "png" ], "type": "string", "description": "Output image format." }, "images": { "description": "Images to edit or blend. 1 to 10 images, each at most 30 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 10, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 30000000 } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "images", "prompt", "resolution" ] }, { "required": [ "aspect_ratio", "prompt", "resolution" ], "properties": { "images": false } } ] }, "SubmitBody_seedream_50_pro": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_seedream_50_pro" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_sora_2_pro": { "description": "Model-specific inputs for `sora-2-pro`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 5000 characters.", "maxLength": 5000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "720p", "1080p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 4000, 8000, 12000 ], "type": "integer" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 } }, "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution", "start_image" ] }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "properties": { "start_image": false } } ] }, "SubmitBody_sora_2_pro": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_sora_2_pro" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_topaz_image_upscaler": { "description": "Model-specific inputs for `topaz-image-upscaler`.", "type": "object", "properties": { "source_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "The image to upscale. At most 30 MB.", "media_type": "image", "role": "reference", "max_file_size_bytes": 30000000 }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "target_resolution": { "description": "Short edge of the upscaled image. The long edge follows the source's aspect ratio.", "enum": [ "1080p", "2K", "4K" ], "type": "string" }, "face_recovery": { "default": "off", "description": "Restore facial detail, and how strongly. Off leaves faces to the general upscale.", "enum": [ "off", "low", "medium", "high" ], "type": "string" }, "face_recovery_creativity": { "default": "none", "description": "How much a recovered face may be reimagined rather than reconstructed. Takes effect only with face_recovery on.", "enum": [ "none", "low", "medium", "high" ], "type": "string" } }, "required": [ "source_image", "target_resolution" ], "additionalProperties": false }, "SubmitBody_topaz_image_upscaler": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_topaz_image_upscaler" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_topaz_image_upscaler_transparency": { "description": "Model-specific inputs for `topaz-image-upscaler-transparency`.", "type": "object", "properties": { "source_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "The image to upscale. At most 30 MB.", "media_type": "image", "role": "reference", "max_file_size_bytes": 30000000 }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] } }, "required": [ "source_image" ], "additionalProperties": false }, "SubmitBody_topaz_image_upscaler_transparency": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_topaz_image_upscaler_transparency" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_topaz_image_upscaler_wonder": { "description": "Model-specific inputs for `topaz-image-upscaler-wonder`.", "type": "object", "properties": { "source_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "The image to upscale. At most 30 MB.", "media_type": "image", "role": "reference", "max_file_size_bytes": 30000000 }, "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "target_resolution": { "description": "Short edge of the upscaled image. The long edge follows the source's aspect ratio.", "enum": [ "1080p", "2K", "4K" ], "type": "string" }, "enhancement_strength": { "default": "high", "description": "How far the generative pass may depart from the source. Lower values stay closer to the original pixels; higher values invent more detail.", "enum": [ "low", "medium", "high" ], "type": "string" }, "film_grain": { "default": false, "description": "Add film grain to the upscaled image, which hides the over-smooth look generative upscaling can leave.", "type": "boolean" } }, "required": [ "source_image", "target_resolution" ], "additionalProperties": false }, "SubmitBody_topaz_image_upscaler_wonder": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_topaz_image_upscaler_wonder" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_topaz_video_upscaler": { "description": "Model-specific inputs for `topaz-video-upscaler`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "The video to upscale. At most 600s and at most 524.2 MB.", "media_type": "video", "role": "input_video", "max_duration_ms": 600000, "max_file_size_bytes": 524288000 }, "resolution": { "description": "Output resolution.", "enum": [ "1080p", "2K", "4K" ], "type": "string" }, "fps_engine": { "enum": [ "standard", "high" ], "type": "string", "description": "Interpolate the output to 60fps with this engine. Omit to keep the source rate; a source already at 60fps or faster keeps its own. 'high' doubles the charge." }, "tuning": { "default": "standard", "description": "Where the enhancement parameters come from: 'standard' uses Hedra's per-resolution presets, 'auto' lets Topaz estimate them from the source.", "enum": [ "standard", "auto" ], "type": "string" } }, "required": [ "resolution", "source_video" ], "additionalProperties": false }, "SubmitBody_topaz_video_upscaler": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_topaz_video_upscaler" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_topaz_video_upscaler_hyperion_2_5": { "description": "Model-specific inputs for `topaz-video-upscaler-hyperion-2-5`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "The SDR video to convert. Its frames may hold at most 14,745,600 pixels (5120x2880). At most 600s and at most 524.2 MB.", "media_type": "video", "role": "input_video", "max_duration_ms": 600000, "max_file_size_bytes": 524288000 } }, "required": [ "source_video" ], "additionalProperties": false }, "SubmitBody_topaz_video_upscaler_hyperion_2_5": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_topaz_video_upscaler_hyperion_2_5" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_topaz_video_upscaler_starlight_fast": { "description": "Model-specific inputs for `topaz-video-upscaler-starlight-fast`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "The video to upscale. At most 300s and at most 524.2 MB.", "media_type": "video", "role": "input_video", "max_duration_ms": 300000, "max_file_size_bytes": 524288000 }, "resolution": { "description": "Output resolution.", "enum": [ "1080p", "2K", "4K" ], "type": "string" }, "reduce_sharpening": { "default": false, "description": "Soften the diffusion pass, which suits sources the default sharpening renders harshly.", "type": "boolean" } }, "required": [ "resolution", "source_video" ], "additionalProperties": false }, "SubmitBody_topaz_video_upscaler_starlight_fast": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_topaz_video_upscaler_starlight_fast" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_topaz_video_upscaler_starlight_hq": { "description": "Model-specific inputs for `topaz-video-upscaler-starlight-hq`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "The video to upscale. At most 300s and at most 524.2 MB.", "media_type": "video", "role": "input_video", "max_duration_ms": 300000, "max_file_size_bytes": 524288000 }, "resolution": { "description": "Output resolution.", "enum": [ "1080p", "2K", "4K" ], "type": "string" }, "reduce_sharpening": { "default": false, "description": "Soften the diffusion pass, which suits sources the default sharpening renders harshly.", "type": "boolean" } }, "required": [ "resolution", "source_video" ], "additionalProperties": false }, "SubmitBody_topaz_video_upscaler_starlight_hq": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_topaz_video_upscaler_starlight_hq" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_topaz_video_upscaler_starlight_precise": { "description": "Model-specific inputs for `topaz-video-upscaler-starlight-precise`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "The video to upscale. At most 300s and at most 524.2 MB.", "media_type": "video", "role": "input_video", "max_duration_ms": 300000, "max_file_size_bytes": 524288000 }, "resolution": { "description": "Output resolution.", "enum": [ "1080p", "2K", "4K" ], "type": "string" }, "reduce_sharpening": { "default": "off", "description": "How far to soften the diffusion pass, for sources the default sharpening renders harshly.", "enum": [ "off", "low", "medium", "high" ], "type": "string" } }, "required": [ "resolution", "source_video" ], "additionalProperties": false }, "SubmitBody_topaz_video_upscaler_starlight_precise": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_topaz_video_upscaler_starlight_precise" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_veed_fabric_10": { "description": "Model-specific inputs for `veed-fabric-10`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "480p", "720p" ], "type": "string" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "audio": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Driving audio. At most 104.8 MB.", "media_type": "audio", "role": "audio_input", "max_file_size_bytes": 104857600 } }, "required": [ "aspect_ratio", "audio", "prompt", "resolution", "start_image" ], "additionalProperties": false }, "SubmitBody_veed_fabric_10": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_veed_fabric_10" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_veed_video_background_removal": { "description": "Model-specific inputs for `veed-video-background-removal`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Video whose background should be made transparent. At most 120s and at most 524.2 MB.", "media_type": "video", "role": "input_video", "max_duration_ms": 120000, "max_file_size_bytes": 524288000 }, "subject_is_person": { "default": true, "description": "Optimize segmentation for a person rather than an object.", "type": "boolean" } }, "required": [ "source_video" ], "additionalProperties": false }, "SubmitBody_veed_video_background_removal": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_veed_video_background_removal" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_veo_2": { "description": "Model-specific inputs for `veo-2`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "type": "string", "description": "Output aspect ratio.", "enum": [ "16:9" ] }, "resolution": { "type": "string", "description": "Output resolution.", "enum": [ "720p" ] }, "duration_ms": { "type": "integer", "description": "Duration in ms.", "enum": [ 5000 ] }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 8 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 8000000 }, "negative_prompt": { "type": "string", "description": "What to avoid in the generated video." }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." } }, "required": [ "prompt" ], "additionalProperties": false, "anyOf": [ { "required": [ "prompt", "start_image" ], "properties": { "negative_prompt": false, "seed": false } }, { "required": [ "prompt" ], "properties": { "start_image": false } } ] }, "SubmitBody_veo_2": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_veo_2" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_veo_3": { "description": "Model-specific inputs for `veo-3`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 20000 characters.", "maxLength": 20000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "720p", "1080p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 4000, 6000, 8000 ], "type": "integer" }, "generate_audio": { "default": true, "description": "Whether to generate native audio for the video.", "type": "boolean" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 8 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 8000000 }, "negative_prompt": { "type": "string", "description": "What to avoid in the generated video." }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." }, "quality": { "type": "string", "enum": [ "standard", "fast" ], "description": "Quality level to generate at. `standard` \u2014 the full model, for hero shots. `fast` \u2014 the same model tuned for turnaround, at a lower rate.", "default": "standard" } }, "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution", "start_image" ] }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "properties": { "start_image": false } } ] }, "SubmitBody_veo_3": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_veo_3" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_veo_31": { "description": "Model-specific inputs for `veo-31`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt.", "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "720p", "1080p" ], "type": "string" }, "duration_ms": { "enum": [ 4000, 6000, 8000 ], "type": "integer", "description": "Duration in ms." }, "generate_audio": { "default": true, "description": "Whether to generate native audio for the video.", "type": "boolean" }, "negative_prompt": { "type": "string", "description": "What to avoid in the generated video." }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 20 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 20000000 }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. At most 20 MB.", "media_type": "image", "role": "end_frame", "max_file_size_bytes": 20000000 }, "source_video": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Source video. From 1s to 30s and at most 524.2 MB.", "media_type": "video", "role": "input_video", "min_duration_ms": 1000, "max_duration_ms": 30000, "max_file_size_bytes": 524288000 }, "images": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 3, "minItems": 1, "type": "array", "description": "Reference images. 1 to 3 images, each at most 20 MB.", "media_type": "image", "role": "reference", "max_file_size_bytes": 20000000 }, "seed": { "maximum": 4294967295, "minimum": 0, "type": "integer", "description": "Seed for reproducible output; omit for a random seed. From 0 to 4294967295." }, "quality": { "type": "string", "enum": [ "standard", "fast" ], "description": "Quality level to generate at. `standard` \u2014 the full model, for maximum detail and nuance. `fast` \u2014 the same model tuned for turnaround, at a lower rate.", "default": "standard" } }, "required": [ "aspect_ratio", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_veo_31": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_veo_31" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_vidu_q3": { "description": "Model-specific inputs for `vidu-q3`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 2000 characters.", "maxLength": 2000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." }, "resolution": { "description": "Output resolution.", "enum": [ "540p", "720p", "1080p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000, 16000 ], "type": "integer" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 10.4 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 10485760 }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. At most 10.4 MB.", "media_type": "image", "role": "end_frame", "max_file_size_bytes": 10485760 }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "quality": { "type": "string", "enum": [ "standard", "turbo" ], "description": "Quality level to generate at. `standard` \u2014 the full model. `turbo` \u2014 the same options tuned for turnaround, at a lower rate.", "default": "standard" } }, "required": [ "duration_ms", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "duration_ms", "prompt", "resolution", "start_image" ], "properties": { "aspect_ratio": false, "end_image": false } }, { "required": [ "duration_ms", "end_image", "prompt", "resolution", "start_image" ], "properties": { "aspect_ratio": false } }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "properties": { "end_image": false, "start_image": false } } ] }, "SubmitBody_vidu_q3": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_vidu_q3" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_vidu_q3_reference": { "description": "Model-specific inputs for `vidu-q3-reference`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 2000 characters.", "maxLength": 2000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "seed": { "type": "integer", "description": "Seed for reproducible output; omit for a random seed." }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "540p", "720p", "1080p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000, 16000 ], "type": "integer" }, "images": { "description": "Reference images. 1 to 4 images, each at most 10.4 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 4, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 10485760 } }, "required": [ "aspect_ratio", "duration_ms", "images", "prompt", "resolution" ], "additionalProperties": false }, "SubmitBody_vidu_q3_reference": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_vidu_q3_reference" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_wan_2_7": { "description": "Model-specific inputs for `wan-2-7`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. At most 5000 characters.", "maxLength": 5000, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "negative_prompt": { "maxLength": 500, "type": "string", "description": "What to avoid in the generated video. At most 500 characters." }, "seed": { "maximum": 2147483647, "minimum": 0, "type": "integer", "description": "Seed for reproducible output; omit for a random seed. From 0 to 2147483647." }, "resolution": { "description": "Output resolution.", "enum": [ "720p", "1080p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000 ], "type": "integer" }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 20 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 20000000 }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. At most 20 MB.", "media_type": "image", "role": "end_frame", "max_file_size_bytes": 20000000 }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "4:3", "3:4", "1:1" ], "type": "string" }, "images": { "description": "Reference images. 1 to 4 images, each at most 20 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 4, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 20000000 } }, "required": [ "duration_ms", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "duration_ms", "prompt", "resolution", "start_image" ], "properties": { "aspect_ratio": false, "images": false } }, { "required": [ "aspect_ratio", "duration_ms", "images", "prompt", "resolution" ], "properties": { "duration_ms": { "enum": [ 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000 ] }, "end_image": false, "start_image": false } }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "properties": { "end_image": false, "images": false, "start_image": false } } ] }, "SubmitBody_wan_2_7": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_wan_2_7" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "Input_wan_3_0": { "description": "Model-specific inputs for `wan-3-0`.", "type": "object", "properties": { "num_outputs": { "default": 1, "description": "Number of outputs generated per job. Only 1 is supported.", "type": "integer", "enum": [ 1 ] }, "prompt": { "description": "Generation prompt. From 1 to 5000 characters.", "maxLength": 5000, "minLength": 1, "pattern": "[^\\s\\x1C-\\x1F]", "type": "string" }, "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "adaptive", "16:9", "4:3", "1:1", "3:4", "9:16" ], "type": "string" }, "resolution": { "description": "Output resolution.", "enum": [ "480p", "720p", "1080p" ], "type": "string" }, "duration_ms": { "description": "Duration in ms.", "enum": [ 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000, 16000, 17000, 18000, 19000, 20000, 21000, 22000, 23000, 24000, 25000, 26000, 27000, 28000, 29000, 30000 ], "type": "integer" }, "generate_audio": { "default": true, "description": "Whether to generate native audio for the video.", "type": "boolean" }, "seed": { "maximum": 2147483647, "minimum": 0, "type": "integer", "description": "Seed for reproducible output; omit for a random seed. From 0 to 2147483647." }, "start_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "Start frame. At most 20 MB.", "media_type": "image", "role": "start_frame", "max_file_size_bytes": 20000000 }, "end_image": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ], "description": "End frame. At most 20 MB.", "media_type": "image", "role": "end_frame", "max_file_size_bytes": 20000000 }, "images": { "description": "Reference images. 1 to 10 images, each at most 20 MB.", "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 10, "media_type": "image", "minItems": 1, "role": "reference", "type": "array", "max_file_size_bytes": 20000000 }, "videos": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 5, "minItems": 1, "type": "array", "description": "Reference videos. 1 to 5 videos, each at most 15s and at most 524.2 MB, at most 15s in total.", "media_type": "video", "role": "reference", "max_duration_ms": 15000, "max_total_duration_ms": 15000, "max_file_size_bytes": 524288000 }, "audios": { "items": { "discriminator": { "propertyName": "source" }, "oneOf": [ { "additionalProperties": false, "description": "A file uploaded via POST /v3/files, referenced by the returned url.", "properties": { "source": { "type": "string", "enum": [ "url" ] }, "url": { "description": "A URL returned by POST /v3/files.", "format": "uri", "type": "string" } }, "required": [ "source", "url" ], "type": "object" }, { "additionalProperties": false, "description": "An existing asset you own, referenced by its id.", "properties": { "source": { "type": "string", "enum": [ "asset" ] }, "asset_id": { "description": "The asset's id (`asset_`), as issued by the server \u2014 a completed generation publishes one per output as `outputs[].asset_id`. Do not construct one or derive it from any other id.", "type": "string" } }, "required": [ "source", "asset_id" ], "type": "object" } ] }, "maxItems": 5, "minItems": 1, "type": "array", "description": "Reference audios. 1 to 5 audio files, each at most 15s and at most 104.8 MB, at most 15s in total.", "media_type": "audio", "role": "reference", "max_duration_ms": 15000, "max_total_duration_ms": 15000, "max_file_size_bytes": 104857600 }, "quality": { "type": "string", "enum": [ "standard", "prime" ], "description": "Quality level to generate at. `standard` \u2014 the base tier. `prime` \u2014 Wan's higher-fidelity tier over the same options, for final output.", "default": "standard" } }, "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "additionalProperties": false, "anyOf": [ { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution", "start_image" ], "properties": { "audios": false, "images": false, "videos": false } }, { "required": [ "aspect_ratio", "duration_ms", "images", "prompt", "resolution" ], "properties": { "end_image": false, "start_image": false } }, { "required": [ "aspect_ratio", "duration_ms", "prompt", "resolution" ], "properties": { "audios": false, "end_image": false, "images": false, "start_image": false, "videos": false } } ] }, "SubmitBody_wan_3_0": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/Input_wan_3_0" }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "SubmitBody": { "type": "object", "properties": { "input": { "type": "object", "additionalProperties": true, "description": "Model-specific inputs, validated at submit against the model's published input schema (`GET /v3/models/{model}`)." }, "webhook": { "type": [ "string", "null" ], "format": "uri", "description": "URL to receive a signed completion webhook.", "default": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Replays the original ack for a retried submit instead of enqueueing a duplicate job.", "default": null } }, "required": [ "input" ] }, "WebhookPayload": { "properties": { "job_id": { "type": "string", "title": "Job Id", "description": "The job this envelope describes." }, "model": { "type": "string", "title": "Model", "description": "The resolved model id this job ran on." }, "quality": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quality", "description": "The quality level this job ran at; present only for models that offer quality levels." }, "status": { "$ref": "#/components/schemas/JobStatus" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt", "description": "The prompt this job ran with. When `enhance_prompt` was set, this is the rewritten prompt the model received rather than the one submitted. Absent on models that take no prompt." }, "outputs": { "items": { "$ref": "#/components/schemas/OutputItem" }, "type": "array", "title": "Outputs", "description": "The job's outputs \u2014 always an array, even for a single output; empty until the job completes." }, "metrics": { "anyOf": [ { "$ref": "#/components/schemas/Metrics" }, { "type": "null" } ], "description": "Timing for this job; present on completed jobs only." }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "type": "null" } ], "description": "Why the job failed; null unless `status` is `FAILED`." } }, "type": "object", "required": [ "job_id", "model", "status" ], "title": "WebhookPayload", "description": "Body of a webhook delivery: the `GET /jobs/{job_id}` result envelope without its poll-only fields (`logs`, `cost`, `currency`) \u2014 poll the job to read those." }, "BillingEventType": { "description": "The billing events an outbound webhook announces.\n\nSeparate from `WebhookEventType`, which names the events of the job\ndeliveries `GET /webhooks/deliveries` lists. `GET /webhooks/deliveries`\ndoes not list these.", "enum": [ "billing.top_off_failed" ], "title": "BillingEventType", "type": "string" }, "TopOffFailureReason": { "description": "Why an automatic top-up did not add funds.", "enum": [ "payment_method_declined" ], "title": "TopOffFailureReason", "type": "string" }, "TopOffFailedEvent": { "description": "Body of a `billing.top_off_failed` webhook.\n\nHedra sends this event when Stripe declines the payment method for an\nautomatic top-up of the API wallet. After a decline, Hedra holds further\nautomatic top-ups until the hold expires, the payment method changes or a\ntop-up is paid, and sends no event for a decline while a hold is in place.", "properties": { "id": { "description": "The event's id, the same value as `X-Hedra-Webhook-Id`.", "title": "Id", "type": "string" }, "type": { "$ref": "#/components/schemas/BillingEventType", "default": "billing.top_off_failed", "description": "Always `billing.top_off_failed`." }, "created_at": { "description": "When the top-up was declined.", "format": "date-time", "title": "Created At", "type": "string" }, "reason": { "$ref": "#/components/schemas/TopOffFailureReason" }, "amount_attempted": { "description": "The amount the top-up tried to add.", "title": "Amount Attempted", "type": "number" }, "balance": { "description": "The API wallet's balance when this event was sent.", "title": "Balance", "type": "number" }, "currency": { "default": "USD", "description": "ISO-4217 currency code for every amount in this event.", "title": "Currency", "type": "string" } }, "required": [ "id", "type", "created_at", "reason", "amount_attempted", "balance", "currency" ], "title": "TopOffFailedEvent", "type": "object" } }, "securitySchemes": { "KeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Primary scheme: `Authorization: Key :`." }, "BearerToken": { "type": "http", "scheme": "bearer", "description": "`Authorization: Bearer ` \u2014 accepts an API key (`:`) or an ephemeral browser token minted via `POST /tokens` (inherits the minting key's scopes and workspace)." } } }, "tags": [ { "name": "Run a model", "description": "One typed submit endpoint per model \u2014 titled `Run ()`, so the model you know by name is the operation you call. Every one returns the same `202` job envelope; track it under Jobs.\n\n`POST /models/{model}` is the same call with the id supplied at runtime and `input` untyped \u2014 use it for a model your client was generated before, or one you looked up in `GET /models`." }, { "name": "Models", "description": "Discover models and estimate cost." }, { "name": "Jobs", "description": "Poll, stream, and list submitted jobs." }, { "name": "Webhooks", "description": "Configure, test, verify, and inspect outbound webhooks.\n\n**Delivery and retries.** Delivery is at-least-once. A `2xx` from your endpoint is success; anything else \u2014 including a redirect, which is never followed \u2014 is retried. Hedra makes up to **12 attempts over approximately 6 hours**, backing off 10s, 30s, 90s, 4m30s, 13m30s, 40m30s, then hourly. An endpoint that is unreachable for the whole window is marked `FAILED` and is not retried again; replay it with `POST /webhooks/deliveries/{job_id}/redeliver`. Two failures are permanent and stop the ladder immediately: a URL that resolves to a blocked address range, and a redirect pointing at one.\n\nBecause the retry window is bounded, respond quickly and do your own processing asynchronously \u2014 acknowledge with a `2xx` first.\n\n**Deduplication.** Key on **`X-Hedra-Webhook-Id`**. It identifies the *event* \u2014 it is the job's own id, and it is byte-identical across every retry and every replay. Do **not** hash the request body: each attempt re-signs the output URL, so the body legitimately differs between attempts of the same event and a body hash would treat every retry as new.\n\nEach POST also carries `X-Hedra-Webhook-Attempt` (1-based, informational) and **`X-Hedra-Webhook-Redelivery`** (`true` / `false`). Redelivery is the exception to deduplication: when it is `true`, an operator asked for this event to be sent again \u2014 process it even if you have already recorded that id, because that request is the whole reason it was sent.\n\n**Inspecting deliveries.** `GET /webhooks/deliveries` reports each delivery's cumulative `attempts`, its latest outcome (`status`, `last_response_status`, `last_error`), and its replay history: `redelivery_count` counts operator replays, and `redeliveries` archives the outcome each replay superseded \u2014 a replay re-sends on the same delivery record and never erases the previous result. Each entry's `attempts` value is the cumulative total when that replay was requested, so the per-cycle attempt counts (and any total beyond the 12-attempt ladder) can be read off the record directly.\n\n**Why a delivery failed.** `last_error` \u2014 on the delivery and on every archived replay entry \u2014 is the same error envelope a failed job returns from `GET /jobs/{job_id}`, not a free-text diagnostic. Its `code` comes from the one error vocabulary this API uses, narrowed for delivery to this set:\n\n| `code` | Means |\n| --- | --- |\n| `DEADLINE_EXCEEDED` | Your endpoint did not respond before the delivery timeout. |\n| `UNAVAILABLE` | Your endpoint could not be reached (DNS, TLS, or connection failure) or answered `5xx` \u2014 or redirected, which is never followed. |\n| `RESOURCE_EXHAUSTED` | Your endpoint answered `429`. |\n| `UNAUTHORIZED` | Your endpoint answered `401`. |\n| `PERMISSION_DENIED` | Your endpoint answered `403`. |\n| `NOT_FOUND` | Your endpoint answered `404`. |\n| `INVALID_ARGUMENT` | Your endpoint answered some other `4xx`. |\n| `FAILED_PRECONDITION` | The URL is not a permitted webhook target \u2014 it resolves to a blocked address range, or redirects to one. Fix the URL; replaying will not help. |\n| `INTERNAL` | Hedra could not build the payload. |\n| `UNKNOWN` | No classification is available, including for deliveries that failed before this field became structured. |\n\n`retryable` describes the condition, not what Hedra did: every non-2xx response is retried on the ladder above, so it answers whether replaying the delivery is likely to help. The `message` is a fixed summary \u2014 your endpoint's URL, address, headers, credentials, and response body are never echoed back, so treat your own logs, not this field, as the record of what your endpoint returned.\n\n**Verifying a delivery.** Every request carries `X-Hedra-Webhook-Signature`, a hex-encoded ed25519 signature over a canonical string of **five newline-separated fields, in this order**:\n\n```\n{X-Hedra-Webhook-Timestamp}\n{X-Hedra-Webhook-Id}\n{X-Hedra-Webhook-Event}\n{X-Hedra-Webhook-Redelivery}\n{sha256 hex digest of the raw request body}\n```\n\nRebuild that string from the request you received, verify it against the key from `GET /webhooks/public-key`, and reject the delivery if the timestamp is more than 5 minutes old. Hash the body **exactly as received**, before any JSON parsing or re-serialization.\n\nThe signature deliberately covers the deduplication id and the redelivery flag, not just the body \u2014 both of them decide whether you process a duplicate, so an unsigned copy of either would let anyone who captured a delivery replay it past your idempotency check. Verify *before* you act on any header. `X-Hedra-Webhook-Attempt` is outside the signature and is informational only; do not branch on it." }, { "name": "Log drains", "description": "Stream signed job lifecycle logs to HTTPS destinations.\n\n**Why the last batch failed.** `last_error` is the same error envelope a failed job returns from `GET /jobs/{job_id}`, not a free-text diagnostic. It is null until a batch fails and is cleared again on the next success. Its `code` comes from the one error vocabulary this API uses, narrowed for drain delivery to this set:\n\n| `code` | Means |\n| --- | --- |\n| `DEADLINE_EXCEEDED` | Your destination did not respond before the delivery timeout. |\n| `UNAVAILABLE` | Your destination could not be reached (DNS, TLS, or connection failure) or answered `5xx` \u2014 or redirected, which is never followed. |\n| `RESOURCE_EXHAUSTED` | Your destination answered `429`. |\n| `UNAUTHORIZED` | Your destination answered `401`. |\n| `PERMISSION_DENIED` | Your destination answered `403`. |\n| `NOT_FOUND` | Your destination answered `404`. |\n| `INVALID_ARGUMENT` | Your destination answered some other `4xx`. |\n| `FAILED_PRECONDITION` | The URL is not a permitted log drain target \u2014 it resolves to a blocked address range. Fix the URL; retrying will not help. |\n| `INTERNAL` | Hedra could not prepare the batch. |\n| `UNKNOWN` | No classification is available, including for drains that last failed before this field became structured. |\n\n`retryable` describes the condition, not what Hedra did: every failed batch is requeued until the drain auto-disables, so it answers whether fixing the destination and re-enabling is likely to help. The `message` is a fixed summary \u2014 your destination's URL, headers, credentials, and response body are never echoed back, so treat your own logs, not this field, as the record of what your destination returned.\n\n`disabled_reason` answers a different question and stays its own small vocabulary: `consecutive_failures` when five batches in a row failed, `disabled_by_user` when you turned the drain off." }, { "name": "Access", "description": "API keys, browser tokens, and file uploads." }, { "name": "Billing", "description": "Balance and usage, in US dollars." } ], "webhooks": { "job.completed": { "post": { "tags": [ "Webhooks" ], "operationId": "webhook_job_completed", "summary": "Webhook: job.completed", "description": "POSTed to the job's registered webhook URL when the job completes. Delivery is at-least-once: dedupe on `X-Hedra-Webhook-Id` and verify `X-Hedra-Webhook-Signature` before acting.", "parameters": [ { "name": "X-Hedra-Webhook-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Deduplication id: the job's own id (`job_`), byte-identical across every retry and every replay. Signed." }, { "name": "X-Hedra-Webhook-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds the delivery was signed at; reject it when more than 5 minutes old. Signed." }, { "name": "X-Hedra-Webhook-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "job.completed" }, "description": "The event this delivery announces. Signed." }, { "name": "X-Hedra-Webhook-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "1-based attempt number within the current delivery cycle. Informational and outside the signature; do not branch on it." }, { "name": "X-Hedra-Webhook-Redelivery", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "`true` when an operator asked for this event to be sent again \u2014 process it even if its id was already recorded. Signed." }, { "name": "X-Hedra-Webhook-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Hex-encoded ed25519 signature over the canonical string documented on the Webhooks tag; verify against the key from `GET /webhooks/public-key` before acting on the request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "2XX": { "description": "Acknowledged; any `2xx` stops the retry ladder. Other responses are retried per the Webhooks tag." } } } }, "job.failed": { "post": { "tags": [ "Webhooks" ], "operationId": "webhook_job_failed", "summary": "Webhook: job.failed", "description": "POSTed to the job's registered webhook URL when the job fails; the payload's `error` carries the same envelope the poll endpoint returns. Delivery is at-least-once: dedupe on `X-Hedra-Webhook-Id` and verify `X-Hedra-Webhook-Signature` before acting.", "parameters": [ { "name": "X-Hedra-Webhook-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Deduplication id: the job's own id (`job_`), byte-identical across every retry and every replay. Signed." }, { "name": "X-Hedra-Webhook-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds the delivery was signed at; reject it when more than 5 minutes old. Signed." }, { "name": "X-Hedra-Webhook-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "job.failed" }, "description": "The event this delivery announces. Signed." }, { "name": "X-Hedra-Webhook-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "1-based attempt number within the current delivery cycle. Informational and outside the signature; do not branch on it." }, { "name": "X-Hedra-Webhook-Redelivery", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "`true` when an operator asked for this event to be sent again \u2014 process it even if its id was already recorded. Signed." }, { "name": "X-Hedra-Webhook-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Hex-encoded ed25519 signature over the canonical string documented on the Webhooks tag; verify against the key from `GET /webhooks/public-key` before acting on the request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "2XX": { "description": "Acknowledged; any `2xx` stops the retry ladder. Other responses are retried per the Webhooks tag." } } } }, "billing.top_off_failed": { "post": { "tags": [ "Webhooks" ], "operationId": "webhook_billing_top_off_failed", "summary": "Webhook: billing.top_off_failed", "description": "POSTed to the default webhook URL when Stripe declines the payment method for an automatic top-up of the API wallet. After a decline, Hedra holds further automatic top-ups until the hold expires, the payment method changes or a top-up is paid, and sends no event for a decline while a hold is in place. Retried on the same schedule as a job delivery, but not listed by `GET /webhooks/deliveries` and cannot be redelivered. Dedupe on `X-Hedra-Webhook-Id` and verify `X-Hedra-Webhook-Signature` before acting.", "parameters": [ { "name": "X-Hedra-Webhook-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Deduplication id: the event's own id (`evt_`), byte-identical across every retry. Signed." }, { "name": "X-Hedra-Webhook-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds the delivery was signed at; reject it when more than 5 minutes old. Signed." }, { "name": "X-Hedra-Webhook-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "billing.top_off_failed" }, "description": "The event this delivery announces. Signed." }, { "name": "X-Hedra-Webhook-Attempt", "in": "header", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "1-based attempt number within the current delivery cycle. Informational and outside the signature; do not branch on it." }, { "name": "X-Hedra-Webhook-Redelivery", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "`true` when an operator asked for this event to be sent again \u2014 process it even if its id was already recorded. Signed." }, { "name": "X-Hedra-Webhook-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Hex-encoded ed25519 signature over the canonical string documented on the Webhooks tag; verify against the key from `GET /webhooks/public-key` before acting on the request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopOffFailedEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged; any `2xx` stops the retry ladder. Other responses are retried per the Webhooks tag." } } } } } }