# API Keys Source: https://docs.deapi.ai/api-keys Key roles (ADMIN and API), the optional restrictions you can set on each key (expiration, spend limit and IP allowlist), and managing keys via the API. Every request is authenticated with an API key sent in the `Authorization: Bearer ` header. Create and manage keys in **Dashboard → Settings → API Keys**. Give each project, teammate or end customer its own key, scoped to exactly what it needs: what it may do, for how long, how much it may spend, and where it may be called from. A key looks like `sk-dp--`. Use it as is everywhere: the native API, the [OpenAI-compatible endpoint](/openai-compatibility), the [MCP server](/execution-modes-and-integrations/mcp-server) and WebSockets. Keys created before this format look like `|` and keep working unchanged. ## Key roles Every key has one of two roles, chosen when the key is created. The role cannot be changed later — to change it, create a new key. * **API key** — runs inference (images, video, audio, …). It has no access to account billing or to other keys: for example, [Check Balance](/api/v2/utilities/balance) returns `403` `insufficient_permissions`. Use it for applications, integrations and keys you hand out per project or per end customer. * **ADMIN key** — full access to the account: inference, account billing and key management. > [!WARNING] > > Keys created before roles were introduced are **ADMIN** keys, so existing integrations keep working unchanged. If a key only needs to run inference, replace it with a new API key and delete the old one. > [!TIP] > > Treat an ADMIN key like a password: keep it server-side and never ship it in client apps. Use API keys everywhere else. ## Key restrictions Each key can carry any combination of the restrictions below — set them when creating the key or change them later. Changes apply from the next request; there is no need to recreate the key. | Restriction | What it does | Default | | - | - | - | | **Expiration date** | The key stops working after this date. Presets: 1 hour, 1 day, 7, 30, 90 or 180 days, 1 year, or a custom date. Extending the date brings an expired key back. | No expiration | | **Spend limit (USD)** | Hard cap on what the key may spend. Once reached, the key rejects new jobs until the limit resets or is raised. | No limit | | **Reset window** | How often the spend counter returns to zero: never, daily, weekly or monthly. Windows run in UTC and are anchored to the moment the key was created. | Never | | **IP allowlist** | The key works only from the listed IPv4/IPv6 addresses or CIDR ranges (up to 20 entries). | Any IP | > [!WARNING] > > Keys with an IP allowlist do not work with the [OpenAI-compatible endpoint](/openai-compatibility) at `https://oai.deapi.ai/v1`. Call the native API at `https://api.deapi.ai` with such keys, or use a key without an IP allowlist for the OpenAI-compatible endpoint. Good to know about the spend limit: * **Changing the limit does not reset the counter.** Raising a limit from \$50 to \$100 after spending \$50 leaves \$50 of headroom. Lowering it below the amount already spent blocks the key until the window resets. * **A limit is a ceiling, not a budget.** A key never spends more than the account balance, and the limits of all keys together may exceed it. * A refunded (failed) job gives its cost back to the key's limit. Rejected requests — expired, disabled, outside the allowlist or over the limit — do not create a job and are not charged. ## Number of keys An account can have up to **100 active keys**. Expired, disabled and deleted keys do not count — disabling a key frees its slot immediately. ## Managing keys via the API Everything you can do with keys in the Dashboard can also be done over the API, using the same `Authorization: Bearer ` header. All paths below are relative to `https://api.deapi.ai`. ### Any key: inspect itself Both roles can read their own state and usage: | Endpoint | What it returns | | - | - | | [`GET /api/v2/key`](/api/v2/keys/get-current-key) | The calling key: name, preview, role, status (`active`, `revoked` — disabled — or `expired`), creation and expiration dates, spend limit and reset window, spend in the current window, remaining amount, next reset, and whether an IP allowlist is on and how many entries it has. The secret is never returned. | | [`GET /api/v2/key/usage`](/api/v2/keys/get-current-key-usage) | The calling key's usage over a time window: cost, number of requests and number of errors. Takes `from`, `to` and `group_by` (`day`, `hour`, `type` or `model`). It shows nothing about other keys or the account balance. | ```bash theme={null} curl https://api.deapi.ai/api/v2/key \ -H "Authorization: Bearer $DEAPI_KEY" ``` This lets an application check how much of its limit is left, or when the limit resets, before it sends a job. ### ADMIN key: manage all keys An ADMIN key can also manage every key on the account. An API key gets `403` `insufficient_permissions` on all of these endpoints. | Endpoint | What it does | | - | - | | [`GET /api/v2/keys`](/api/v2/keys/list-keys) | Lists the account's keys: id, name, preview, role, status, spend limit and window, spend in the current window, expiration date, number of allowlist entries and last use. Secrets are never returned. | | [`POST /api/v2/keys`](/api/v2/keys/create-key) | Creates an **API** key. Takes a name, expiration date, spend limit, reset window and IP allowlist. Creating an ADMIN key this way is rejected with `403`. | | [`GET /api/v2/keys/{id}`](/api/v2/keys/get-key) | Details of one key: the same fields as `GET /api/v2/key`. | | [`PATCH /api/v2/keys/{id}`](/api/v2/keys/update-key) | Changes the spend limit, reset window, expiration date or IP allowlist, or disables / re-enables the key. The role cannot be changed. | | [`DELETE /api/v2/keys/{id}`](/api/v2/keys/delete-key) | Deletes the key permanently. Its past usage stays in usage reports. | | [`GET /api/v2/keys/{id}/usage`](/api/v2/keys/get-key-usage) | Usage of one key, with the same parameters as `GET /api/v2/key/usage`. | > [!WARNING] > > The secret of a new key is returned **only once**, in the response to `POST /api/v2/keys`. No other endpoint returns it. Store it straight away; if it is lost, create a new key and delete the old one. Creating keys is rate-limited. Too many in a short time returns `429` `rate_limited`. ### ADMIN key: account billing and usage | Endpoint | What it returns | | - | - | | [`GET /api/v2/account`](/api/v2/account/get-account) | Account billing: balance, currency, auto top-up status, top-up threshold and top-up amount. | | [`GET /api/v2/account/usage`](/api/v2/account/usage) | Usage of the whole account over a time window — the same data as the Usage screen in the Dashboard. Takes `from`, `to` and `group_by` (`day`, `hour`, `key`, `type` or `model`). | | [`GET /api/v2/account/payments`](/api/v2/account/payments) | History of payments and top-ups. | With `group_by=key`, each group's `key` is one of: * **a number** — the id of an existing key, * `panel` — jobs started from the Dashboard itself, such as the Playground (`name: "Panel"`), * `deleted` — all keys that have since been deleted, combined (`name: "Deleted keys"`), * `null` — requests with no usage log, where the source is unknown. ## Error codes Key-related rejections carry a machine-readable `code` field next to `message`: | HTTP | `code` | When | | - | - | - | | `401` | `missing_key` | The request has no `Authorization` header. | | `401` | `invalid_key` | The key does not exist or is malformed. | | `401` | `key_expired` | The key's expiration date has passed. | | `401` | `key_revoked` | The key was disabled in the Dashboard or via the API. | | `402` | `key_limit_exceeded` | The key's spend limit is used up. The response also carries `limit`, `used`, `remaining` and `resets_at` (the next reset, or `null` if the limit never resets). | | `403` | `ip_not_allowed` | The request came from an address outside the key's IP allowlist. | | `403` | `insufficient_permissions` | An API key called an endpoint that requires an ADMIN key, such as the account balance or key management. | | `422` | `active_key_limit_reached` | Creating or re-enabling a key over the API would exceed the limit of 100 active keys. | | `422` | `insufficient_balance` | The account balance is too low. Top up and retry the same request. | | `429` | `rate_limited` | Too many requests, or too many keys created in a short time. | # Audio-to-Text (X Spaces Transcription) Source: https://docs.deapi.ai/api/v1/analysis/audio-to-text-spaces openapi-v1.json POST /api/v1/client/aud2txt Endpoint for requesting audio transcription (Twitter Spaces) > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug`, check specific **limits** and **features**, and verify **LoRA** availability. ## Technical Notes & Constraints ### Spaces Support * **Completed Spaces Only**: The API does not support live (ongoing) X Spaces. If a URL for an active Space is provided, the API will return a validation error. Please ensure the Space has ended before submission. * **Max Duration**: 90 minutes ### Progress Tracking (URL/Spaces) * **Download Phase:** Due to external stream handling, the task progress will remain at 0% for the entire duration of the audio download. * **Transcription Phase**: Once the download is complete, the progress status will jump to 50% and update incrementally until finished. * A prolonged 0% status is normal behavior for long X Spaces. > [!NOTE] > > Transcription for standard video posts on X is handled via the [Video-to-Text](/api/v1/analysis/video-to-text) endpoint. # Audio-to-Text (X Spaces) Price Calculation Source: https://docs.deapi.ai/api/v1/analysis/audio-to-text-spaces-price openapi-v1.json POST /api/v1/client/aud2txt/price-calculation Endpoint for calculating price for audio to text inference (Twitter Spaces) > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Image-to-Text (OCR) Source: https://docs.deapi.ai/api/v1/analysis/image-to-text openapi-v1.json POST /api/v1/client/img2txt Endpoint for requesting image2text (OCR) inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug`, check specific **limits** and **features**, and verify **LoRA** availability. # Image-to-Text Price Calculation Source: https://docs.deapi.ai/api/v1/analysis/image-to-text-price openapi-v1.json POST /api/v1/client/img2txt/price-calculation Endpoint for calculating price for image2text (OCR) inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Transcribe (Unified Transcription) Source: https://docs.deapi.ai/api/v1/analysis/transcribe openapi-v1.json POST /api/v1/client/transcribe A single endpoint for all transcription needs — URL-based (YouTube, X, Twitch, Kick, TikTok, X Spaces) and file uploads (audio & video). Replaces vid2txt, aud2txt, videofile2txt, and audiofile2txt with automatic source detection. > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug`, check specific **limits** and **features**. ## How it works Provide exactly **one** of: * `source_url` — a URL to transcribe (YouTube, X/Twitter, Twitch, Kick, TikTok, or X Spaces) * `source_file` — an uploaded audio or video file The endpoint auto-detects the source type and routes the job accordingly. All existing transcription features (timestamps, webhook notifications) are fully supported. > [!WARNING] > > **TikTok requires `WhisperLargeV3Ct2`.** A TikTok `source_url` sent with any other model — `WhisperLargeV3` included — is rejected with `422` and nothing is charged. Every other source runs on either model. Note that the v1 [Model Selection](/api/v1/utilities/model-selection) endpoint does not list `WhisperLargeV3Ct2`, but v1 accepts the slug; v2 lists it normally. ### Supported file formats | Type | Formats | | - | - | | Audio | AAC, MPEG, OGG, WebM | | Video | MP4, MPEG, QuickTime, AVI, WMV, OGG | ### Inline results Set `return_result_in_response: true` to receive the transcription text directly in the API response instead of a download URL. Useful for short content or real-time integrations. > [!NOTE] > > The four legacy endpoints (`vid2txt`, `aud2txt`, `videofile2txt`, `audiofile2txt`) remain fully operational. The unified `/transcribe` endpoint is the recommended path for new integrations. # Transcribe Price Calculation Source: https://docs.deapi.ai/api/v1/analysis/transcribe-price openapi-v1.json POST /api/v1/client/transcribe/price-calculation Unified endpoint for calculating transcription price. Provide one of: source_url, source_file, or duration_seconds. > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Upload Audio File (Audio-to-Text) Source: https://docs.deapi.ai/api/v1/analysis/upload-audio-file openapi-v1.json POST /api/v1/client/audiofile2txt Endpoint for requesting audio transcription > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug`, check specific **limits** and **features**, and verify **LoRA** availability. # Upload Audio File Price Calculation Source: https://docs.deapi.ai/api/v1/analysis/upload-audio-file-price openapi-v1.json POST /api/v1/client/audiofile2txt/price-calculation Endpoint for requesting audio transcription price > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Upload Video File (Video-to-Text) Source: https://docs.deapi.ai/api/v1/analysis/upload-video-file openapi-v1.json POST /api/v1/client/videofile2txt Endpoint for requesting video transcription > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug`, check specific **limits** and **features**, and verify **LoRA** availability. # Upload Video File Price Calculation Source: https://docs.deapi.ai/api/v1/analysis/upload-video-file-price openapi-v1.json POST /api/v1/client/videofile2txt/price-calculation Endpoint for calculating price for video to text inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Video-to-Text (Transcription) Source: https://docs.deapi.ai/api/v1/analysis/video-to-text openapi-v1.json POST /api/v1/client/vid2txt Unique Platform Support: deAPI is one of the few APIs offering direct transcription from YT, TikTok, Twitch VODs, X and Kick videos — no need to download files first. Just paste the URL. > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug`, check specific **limits** and **features**, and verify **LoRA** availability. > [!WARNING] > > **TikTok requires `WhisperLargeV3Ct2`.** A TikTok `video_url` sent with any other model — `WhisperLargeV3` included — is rejected with `422` and nothing is charged. YouTube, Twitch VODs, X and Kick run on either model. Note that the v1 [Model Selection](/api/v1/utilities/model-selection) endpoint does not list `WhisperLargeV3Ct2`, but v1 accepts the slug; v2 lists it normally. # Video-to-Text Price Calculation Source: https://docs.deapi.ai/api/v1/analysis/video-to-text-price openapi-v1.json POST /api/v1/client/vid2txt/price-calculation Endpoint for calculating price for video to text inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Errors Source: https://docs.deapi.ai/api/v1/errors HTTP status codes and error responses returned by deAPI > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). v1 and v2 share the same error envelope — this page mirrors [API v2 → Errors](/api/v2/errors) with v1 paths. deAPI uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error from the provided information (e.g., missing required parameter, unauthorized access). Codes in the `5xx` range indicate an error with deAPI servers. ## HTTP Status Codes | Code | Status | Description | | - | - | - | | `200` | OK | Request succeeded. Response contains requested data. | | `401` | Unauthorized | Invalid or missing API key. | | `404` | Not Found | The requested resource (job, route) does not exist. | | `413` | Payload Too Large | Request body exceeded the upload cap. See [Limits & Quotas](/limits-and-quotas#file-uploads). | | `422` | Unprocessable Entity | Request validation failed. Check the `errors` object for details. | | `429` | Too Many Requests | Rate limit exceeded. | | `500` | Internal Server Error | Something went wrong on our end. Try again later. | ## Error Response Format Every error response carries a top-level `message`. Validation errors (`422`) additionally carry an `errors` object: ```json theme={null} { "message": "The selected model does not exist.", "errors": { "model": ["The selected model does not exist."] } } ``` **message** `string` Human-readable error description. Present on every error response. For a `422` with several failures it summarises the first one and counts the rest, e.g. `"The width field must be at least 512. (and 2 more errors)"`. **errors** `object` **Only present on `422`.** A map of `field name → array of messages`, not an array. A single request can fail on several fields at once, and a single field can carry several messages. > [!WARNING] > > The error body has **no `data` and no `statusCode` field** — read the status from the HTTP response itself. Do not iterate `errors` as an array: it is an object keyed by field name (`errors.model[0]`, not `errors[0].field`). ## Error Types ### 401 Unauthorized Returned when authentication fails. **Common causes:** * Missing `Authorization` header * Invalid API key * Expired or revoked API key ```json theme={null} { "message": "Unauthenticated." } ``` **Solution:** Verify your API key is correct and included in the `Authorization: Bearer ` header. *** ### 404 Not Found Returned when the requested resource doesn't exist. Two different bodies are possible. **Unknown job / resource** — e.g. an invalid `request_id` passed to `GET /api/v1/client/request-status/{request_id}`: ```json theme={null} { "message": "No query results for the requested resource." } ``` > [!NOTE] > > Match on the **status code**, not on the message text. The wording of `404` messages is not part of the API contract and can change. **Unknown route** — e.g. calling a documentation URL instead of the API path: ```json theme={null} { "message": "The route api/v1/utilities/check-balance could not be found." } ``` **Solution:** Verify the `request_id`, and take API paths from the [API Overview](/api/v1/overview) — documentation URLs are not API routes (the real balance route is `/api/v1/client/balance`). > [!NOTE] > > An unknown **model** is not a `404` — it fails validation and returns `422` with `errors.model`. *** ### 422 Unprocessable Entity Returned when request validation fails. `errors` is an object keyed by field name. **Common causes:** * Missing required parameters * Invalid parameter values (out of range, wrong type) * A value outside the selected model's `info.limits` * Invalid image/video URL or format ```json theme={null} { "message": "The width field must be at least 512. (and 2 more errors)", "errors": { "width": ["The width field must be at least 512."], "height": ["The height field must be at least 512."], "steps": ["The steps field must be at least 8."] } } ``` **Solution:** Iterate the keys of the `errors` object to identify which fields failed and correct them. Many limits are model-specific — read `info.limits` from the [Model Selection](/api/v1/utilities/model-selection) endpoint for the model you are calling. *** ### 429 Too Many Requests Returned when you exceed your rate limit. ```json theme={null} { "message": "Too Many Attempts." } ``` Every response carries the current allowance in headers: | Header | Meaning | | - | - | | `X-RateLimit-Limit` | Requests allowed in the current window | | `X-RateLimit-Remaining` | Requests left in the current window | | `X-RateLimit-Source` | Which limit bucket was applied | **Solution:** Back off and retry — see [Limits & Quotas](/limits-and-quotas#rate-limit-errors). *** ### 500 Internal Server Error Returned when an unexpected error occurs on our servers. ```json theme={null} { "message": "Server Error" } ``` **Solution:** Wait a moment and retry your request. If the problem persists, check [status.deapi.ai](https://status.deapi.ai/) or contact support on [Discord](https://discord.com/invite/UFfK5YRBsr). > [!NOTE] > > A job that fails **after** it was accepted does not produce an HTTP error. The submission returns `200` with a `request_id`, and the failure surfaces on the job status as `status: "error"` with `error_code`, `error_message`, `error_reason`, `retryable` and `refunded`. See [Webhooks](/execution-modes-and-integrations/webhooks) for the full value lists. ## Best Practices > [card] Handle all error codes > > Implement error handling for all possible status codes in your application. > [card] Parse the errors object > > For 422 responses, iterate the keys of the `errors` object to display field-specific messages to users. > [card] Implement retry logic > > For 500 errors, implement exponential backoff retry (e.g., 1s, 2s, 4s delays). > [card] Log error responses > > Log full error responses for debugging. Include `request_id` if available. ## Example Error Handling ```python Python theme={null} import requests response = requests.post( "https://api.deapi.ai/api/v1/client/txt2img", headers={ "Authorization": "Bearer YOUR_API_KEY", "Accept": "application/json" }, json={ "prompt": "a cat", "model": "Flux1schnell", "width": 512, "height": 512, "steps": 4, "guidance": 0, "seed": -1, "loras": [] } ) if response.status_code == 200: data = response.json() request_id = data["data"]["request_id"] print(f"Job started: {request_id}") elif response.status_code == 401: print("Authentication failed. Check your API key.") elif response.status_code == 422: error_data = response.json() print(f"Validation error: {error_data['message']}") # `errors` is an object: field name -> list of messages for field, messages in error_data.get("errors", {}).items(): print(f" Field '{field}': {messages}") elif response.status_code == 429: print("Rate limited. Remaining:", response.headers.get("X-RateLimit-Remaining")) elif response.status_code == 500: print("Server error. Retrying...") else: print(f"Unexpected error: {response.status_code}") ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.deapi.ai/api/v1/client/txt2img", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", "Accept": "application/json" }, body: JSON.stringify({ prompt: "a cat", model: "Flux1schnell", width: 512, height: 512, steps: 4, guidance: 0, seed: -1, loras: [] }) }); if (response.ok) { const data = await response.json(); const requestId = data.data.request_id; console.log(`Job started: ${requestId}`); } else if (response.status === 401) { console.error("Authentication failed. Check your API key."); } else if (response.status === 422) { const errorData = await response.json(); console.error(`Validation error: ${errorData.message}`); // `errors` is an object: field name -> array of messages for (const [field, messages] of Object.entries(errorData.errors ?? {})) { console.error(` Field '${field}': ${messages.join(", ")}`); } } else if (response.status === 429) { console.error("Rate limited. Remaining:", response.headers.get("X-RateLimit-Remaining")); } else if (response.status === 500) { console.error("Server error. Retrying..."); } else { console.error(`Unexpected error: ${response.status}`); } ``` # Audio-to-Video Source: https://docs.deapi.ai/api/v1/generation/audio-to-video openapi-v1.json POST /api/v1/client/aud2video Endpoint for requesting audio2video inference Audio-to-Video generates video clips conditioned on an audio file and a text prompt. You can optionally provide first and last frame images to control the visual start and end points. The endpoint returns a task ID to track processing status. > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug`, check specific **limits** and **features**. # Audio-to-Video Price Calculation Source: https://docs.deapi.ai/api/v1/generation/audio-to-video-price openapi-v1.json POST /api/v1/client/aud2video/price-calculation Endpoint for calculating price for audio2video inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Image-to-Video Source: https://docs.deapi.ai/api/v1/generation/image-to-video openapi-v1.json POST /api/v1/client/img2video Endpoint for requesting image2video inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug`, check specific **limits** and **features**, and verify **LoRA** availability. Please **omit** the LoRA parameter by default during initial testing. # Image-to-Video Price Calculation Source: https://docs.deapi.ai/api/v1/generation/image-to-video-price openapi-v1.json POST /api/v1/client/img2video/price-calculation Endpoint for calculating price for image2video inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Text-to-Embedding Source: https://docs.deapi.ai/api/v1/generation/text-to-embedding openapi-v1.json POST /api/v1/client/txt2embedding Endpoint for requesting text to embedding inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug`, check specific **limits** and **features**, and verify **LoRA** availability. # Text-to-Embedding Price Calculation Source: https://docs.deapi.ai/api/v1/generation/text-to-embedding-price openapi-v1.json POST /api/v1/client/txt2embedding/price-calculation Endpoint for calculating price for text to embedding inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Text-to-Image Source: https://docs.deapi.ai/api/v1/generation/text-to-image openapi-v1.json POST /api/v1/client/txt2img Endpoint for requesting text2img inference Text-to-Image generates images from text prompts. The endpoint returns a ready-to-use image URL and a task ID to track processing status. Ideal for apps needing automated image creation. > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug`, check specific **limits** and **features**, and verify **LoRA** availability. Please **omit** the LoRA parameter by default during initial testing. # Text-to-Image Price Calculation Source: https://docs.deapi.ai/api/v1/generation/text-to-image-price openapi-v1.json POST /api/v1/client/txt2img/price-calculation Endpoint for calculating price for text2img inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Text-to-Music Source: https://docs.deapi.ai/api/v1/generation/text-to-music openapi-v1.json POST /api/v1/client/txt2music Endpoint for requesting text2music inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). Text-to-Music generates music tracks from text descriptions. You can control genre, tempo, key, time signature, and even provide lyrics. Optionally upload a `reference_audio` file for style transfer — the model will use it as a stylistic reference for the generated track. The endpoint returns a task ID to track processing status. Ideal for apps needing automated music creation — background tracks, jingles, or full songs with vocals. > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug` and check specific **limits**. ## Field values worth knowing These constraints are enforced by validation and are easy to trip over. They are identical on the v2 endpoint, [`POST /api/v2/audio/music`](/api/v2/audio/music). | Field | Constraint | | - | - | | `lyrics` | **Required and must be non-empty**, including for instrumental tracks. Omitting it or sending `""` returns `422 The lyrics field is required.` For an instrumental track, send `"[Instrumental]"`. | | `timesignature` | **Integer only**, and only `2`, `3`, `4` or `6` are accepted. A notation string such as `"4/4"` returns `422 The timesignature field must be an integer.` Map the numerator of an x/4 signature (4/4 → `4`, 3/4 → `3`, 2/4 → `2`, 6/8 → `6`); 5/4 and 7/8 cannot be expressed. Omit the field or send an empty value to let the model choose. | | `format` | Use `mp3` — the only format the current models actually produce (`info.limits.output_formats`). Anything else returns `422 The selected format is invalid.` | | `keyscale` | Free-form string (`"C major"`, `"D minor"`, `"F# minor"`). Not validated against a fixed list — passed to the model as a hint. | | `vocal_language` | Free-form string. Both ISO codes (`"en"`) and language names (`"English"`) are accepted. Not validated against a fixed list. | > [!WARNING] > > `timesignature` is validated as an **integer**, not as musical notation. If you populate it from a UI dropdown offering values like `4/4` or `6/8`, convert to the integer before sending — otherwise only the requests that set the field fail, while the rest keep succeeding. > [!WARNING] > > **Reference audio requirements (optional):** > > * Supported formats: MP3, OGG, M4A > * Maximum file size: 10 MB (default; configurable) > * Duration must be within model-specific limits — 5–60 s on the ACE-Step models (`info.limits.min_ref_audio_duration` / `max_ref_audio_duration`) > > This endpoint uses `multipart/form-data` content type to support file uploads. # Text-to-Music Price Calculation Source: https://docs.deapi.ai/api/v1/generation/text-to-music-price openapi-v1.json POST /api/v1/client/txt2music/price-calculation Endpoint for calculating price for text2music inference. Requires duration and inference_steps parameters. > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Text-to-Speech (TTS) Source: https://docs.deapi.ai/api/v1/generation/text-to-speech openapi-v1.json POST /api/v1/client/txt2audio Endpoint for requesting text2audio inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). Text-to-Speech converts text into natural-sounding audio. The endpoint supports three TTS modes via the `mode` parameter: * **`custom_voice`** (default) — Use a preset voice from the model's voice library. Requires the `voice` parameter. * **`voice_clone`** — Clone a voice from a short reference audio clip. Requires the `ref_audio` parameter (3–10 seconds, max 15 MB). Optionally provide `ref_text` with a transcript of the reference audio for improved accuracy. * **`voice_design`** — Create a new voice from a natural language description. Requires the `instruct` parameter (e.g. `"A warm female voice with a British accent"`). > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug`, check specific **limits** and **features**, and verify available **languages** and **voices**. > [!WARNING] > > **Mode-specific required fields:** > > * `custom_voice` — `voice` is required. > * `voice_clone` — `ref_audio` is required. `ref_text` is optional but recommended. > * `voice_design` — `instruct` is required. > > If `mode` is omitted, the API defaults to `custom_voice`. # Text-to-Speech Price Calculation Source: https://docs.deapi.ai/api/v1/generation/text-to-speech-price openapi-v1.json POST /api/v1/client/txt2audio/price-calculation Endpoint for calculating price for text2audio inference. Either text or count_text must be provided. > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Text-to-Video Source: https://docs.deapi.ai/api/v1/generation/text-to-video openapi-v1.json POST /api/v1/client/txt2video Endpoint for requesting text2video inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug`, check specific **limits** and **features**, and verify **LoRA** availability. # Text-to-Video Price Calculation Source: https://docs.deapi.ai/api/v1/generation/text-to-video-price openapi-v1.json POST /api/v1/client/txt2video/price-calculation Endpoint for calculating price for text2video inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # API Overview Source: https://docs.deapi.ai/api/v1/overview Complete reference of all deAPI endpoints > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). All endpoints use base URL `https://api.deapi.ai` and require authentication via `Authorization: Bearer ` header. > [!NOTE] > > Each generation/analysis endpoint has a corresponding `/price-calculation` endpoint to estimate costs before execution. ## Relationship to v2 v1 and [v2](/api/v2/overview) are two request surfaces over the same inference backend. For endpoints that exist in both, the request fields, validation rules and validation messages are identical, and jobs are stored in a single namespace — a `request_id` returned by a v1 endpoint can be polled with `GET /api/v2/jobs/{request_id}`, and a `request_id` returned by a v2 endpoint can be polled with `GET /api/v1/client/request-status/{request_id}`. The practical differences are naming and grouping: v1 uses one flat `/api/v1/client/` namespace with `/price-calculation` suffixes, while v2 groups endpoints by media type (`/api/v2/images/*`, `/api/v2/videos/*`, `/api/v2/audio/*`) with `/price` suffixes, and consolidates several v1 endpoints into unified ones (all transcription endpoints into `/api/v2/audio/transcriptions`, all prompt boosters into `/api/v2/prompts/enhancements`). > [!WARNING] > > **API v1 is deprecated.** v1 is no longer being developed — all new endpoints, parameters, models and fixes land in v2 first and are not backported. Existing v1 integrations keep working, but new integrations should be built on v2, and existing ones should plan a migration. > > See the [v2 API documentation](https://docs.deapi.ai/api/v2/overview) for the current endpoint reference. ## Generation Create images, videos, audio, and embeddings from text or images. | Method | Endpoint | Description | Docs | | - | - | - | - | | `POST` | `/api/v1/client/txt2img` | Generate image from text prompt | [→](/api/v1/generation/text-to-image) | | `POST` | `/api/v1/client/txt2img/price-calculation` | Calculate text-to-image price | [→](/api/v1/generation/text-to-image-price) | | `POST` | `/api/v1/client/txt2video` | Generate video from text prompt | [→](/api/v1/generation/text-to-video) | | `POST` | `/api/v1/client/txt2video/price-calculation` | Calculate text-to-video price | [→](/api/v1/generation/text-to-video-price) | | `POST` | `/api/v1/client/img2video` | Generate video from image (animate) | [→](/api/v1/generation/image-to-video) | | `POST` | `/api/v1/client/img2video/price-calculation` | Calculate image-to-video price | [→](/api/v1/generation/image-to-video-price) | | `POST` | `/api/v1/client/aud2video` | Generate video from audio + prompt | [→](/api/v1/generation/audio-to-video) | | `POST` | `/api/v1/client/aud2video/price-calculation` | Calculate audio-to-video price | [→](/api/v1/generation/audio-to-video-price) | | `POST` | `/api/v1/client/txt2audio` | Generate speech from text (TTS) | [→](/api/v1/generation/text-to-speech) | | `POST` | `/api/v1/client/txt2audio/price-calculation` | Calculate text-to-speech price | [→](/api/v1/generation/text-to-speech-price) | | `POST` | `/api/v1/client/txt2embedding` | Generate embeddings from text | [→](/api/v1/generation/text-to-embedding) | | `POST` | `/api/v1/client/txt2embedding/price-calculation` | Calculate embedding price | [→](/api/v1/generation/text-to-embedding-price) | | `POST` | `/api/v1/client/txt2music` | Generate music from text | [→](/api/v1/generation/text-to-music) | | `POST` | `/api/v1/client/txt2music/price-calculation` | Calculate text-to-music price | [→](/api/v1/generation/text-to-music-price) | ## Analysis Extract text and transcriptions from images, videos, and audio. | Method | Endpoint | Description | Docs | | - | - | - | - | | `POST` | `/api/v1/client/img2txt` | Extract text from image (OCR) | [→](/api/v1/analysis/image-to-text) | | `POST` | `/api/v1/client/img2txt/price-calculation` | Calculate OCR price | [→](/api/v1/analysis/image-to-text-price) | | `POST` | `/api/v1/client/vid2txt` | Transcribe video from URL (YouTube, X, TikTok, Twitch, Kick) — TikTok requires `WhisperLargeV3Ct2` | [→](/api/v1/analysis/video-to-text) | | `POST` | `/api/v1/client/vid2txt/price-calculation` | Calculate video transcription price | [→](/api/v1/analysis/video-to-text-price) | | `POST` | `/api/v1/client/aud2txt` | Transcribe X Spaces audio | [→](/api/v1/analysis/audio-to-text-spaces) | | `POST` | `/api/v1/client/aud2txt/price-calculation` | Calculate X Spaces transcription price | [→](/api/v1/analysis/audio-to-text-spaces-price) | | `POST` | `/api/v1/client/videofile2txt` | Transcribe uploaded video file | [→](/api/v1/analysis/upload-video-file) | | `POST` | `/api/v1/client/videofile2txt/price-calculation` | Calculate video file transcription price | [→](/api/v1/analysis/upload-video-file-price) | | `POST` | `/api/v1/client/audiofile2txt` | Transcribe uploaded audio file | [→](/api/v1/analysis/upload-audio-file) | | `POST` | `/api/v1/client/audiofile2txt/price-calculation` | Calculate audio file transcription price | [→](/api/v1/analysis/upload-audio-file-price) | | `POST` | `/api/v1/client/transcribe` | Unified transcription (URL or file upload) | [→](/api/v1/analysis/transcribe) | | `POST` | `/api/v1/client/transcribe/price-calculation` | Calculate unified transcription price | [→](/api/v1/analysis/transcribe-price) | ## Transformation Modify existing images and videos. | Method | Endpoint | Description | Docs | | - | - | - | - | | `POST` | `/api/v1/client/img2img` | Transform image with text prompt | [→](/api/v1/transformation/image-to-image) | | `POST` | `/api/v1/client/img2img/price-calculation` | Calculate image transformation price | [→](/api/v1/transformation/image-to-image-price) | | `POST` | `/api/v1/client/img-rmbg` | Remove image background | [→](/api/v1/transformation/background-removal) | | `POST` | `/api/v1/client/img-rmbg/price-calculation` | Calculate background removal price | [→](/api/v1/transformation/background-removal-price) | | `POST` | `/api/v1/client/img-upscale` | Upscale image resolution | [→](/api/v1/transformation/image-upscale) | | `POST` | `/api/v1/client/img-upscale/price-calculation` | Calculate image upscale price | [→](/api/v1/transformation/image-upscale-price) | | `POST` | `/api/v1/client/vid-upscale` | Upscale video resolution | [→](/api/v1/transformation/video-upscale) | | `POST` | `/api/v1/client/vid-upscale/price-calculation` | Calculate video upscale price | [→](/api/v1/transformation/video-upscale-price) | ## Utilities Account management and job status tracking. | Method | Endpoint | Description | Docs | | - | - | - | - | | `GET` | `/api/v1/client/balance` | Get current account balance | [→](/api/v1/utilities/check-balance) | | `GET` | `/api/v1/client/request-status/{request_id}` | Check job status and get results | [→](/api/v1/utilities/get-results) | | `GET` | `/api/v1/client/models` | List available models — send `?limit=50` for the full list | [→](/api/v1/utilities/model-selection) | ## Workflow Typical API usage follows this pattern: **1. Check available models** Call `GET /api/v1/client/models?limit=50` to get current models and their parameters. That covers the whole catalogue in one call — the page size defaults to 50, and `meta.last_page` reading `1` is what confirms nothing is missing. **2. Calculate price (optional)** Call the `/price-calculation` endpoint with your parameters to estimate cost. **3. Submit job** Call the main endpoint (e.g., `POST /api/v1/client/txt2img`) with your parameters. Response contains `request_id`. **4. Poll for results** Call `GET /api/v1/client/request-status/{request_id}` until `status` is `done` or `error`. **5. Download result** When `status` is `done`, use `result_url` to download your generated content. ## Response Formats ```json Job Submission (txt2img, txt2video, etc.) theme={null} { "data": { "request_id": "c08a339c-73e5-4d67-a4d5-231302fbff9a" } } ``` ```json Job Status (request-status) theme={null} { "data": { "status": "done", "progress": 100.0, "result_url": "https://...", "result": null, "preview": null } } ``` ```json Balance theme={null} { "data": { "balance": 19.72 } } ``` ```json Models List theme={null} { "data": [ { "name": "FLUX.1 Schnell 12B NF4", "slug": "Flux1schnell", "inference_types": ["txt2img"], "tags": [], "status": "standard_model", "info": { ... } } ], "links": { ... }, "meta": { ... } } ``` ```json Error (4xx/5xx) theme={null} { "message": "The selected model does not exist.", "errors": { "model": ["The selected model does not exist."] } } ``` > [!NOTE] > > Response structure varies by endpoint. See individual endpoint documentation for exact schemas. See [Errors](/api/v1/errors) for detailed error handling documentation. # Prompt Enhancement (Removed) Source: https://docs.deapi.ai/api/v1/prompt-enhancement/overview The v1 prompt boosters have been removed. Use the unified v2 Prompt Booster instead. > [!WARNING] > > **The v1 prompt boosters have been removed.** They return **410 Gone** with a `Deprecation: true` header and a `Link` header pointing at the successor. There is no automatic redirect — you must update both the URL and the request fields. > > Use the [**v2 Prompt Booster**](/api/v2/prompt-enhancement/prompt-booster) — `POST /api/v2/prompts/enhancements`. ## Migrating v2 replaces all four boosters with one endpoint. Select the booster with `type` and the target model with `model_slug`. | v1 endpoint (410 Gone) | v2 replacement | | - | - | | `POST /api/v1/client/prompt/image` | `type: images.generations` | | `POST /api/v1/client/prompt/image2image` | `type: images.edits` | | `POST /api/v1/client/prompt/video` | `type: videos.generations` | | `POST /api/v1/client/prompt/speech` | `type: audio.speech` | The four `/price-calculation` variants map the same way to `POST /api/v2/prompts/enhancements/price`. See the [v2 Prompt Enhancement overview](/api/v2/prompt-enhancement/overview) for the full field reference. # Image Background Removal Source: https://docs.deapi.ai/api/v1/transformation/background-removal openapi-v1.json POST /api/v1/client/img-rmbg Endpoint for requesting image background removal inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug`, check specific **limits** and **features**, and verify **LoRA** availability. # Image Background Removal Price Calculation Source: https://docs.deapi.ai/api/v1/transformation/background-removal-price openapi-v1.json POST /api/v1/client/img-rmbg/price-calculation Endpoint for calculating price for image background removal inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Image-to-Image Source: https://docs.deapi.ai/api/v1/transformation/image-to-image openapi-v1.json POST /api/v1/client/img2img Endpoint for requesting img2img inference. Accepts either a single image via "image" or multiple images via "images[]" (mutually exclusive). > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug`, check specific **limits** and **features**, and verify **LoRA** availability. Please **omit** the LoRA parameter by default during initial testing. # Image-to-Image Price Calculation Source: https://docs.deapi.ai/api/v1/transformation/image-to-image-price openapi-v1.json POST /api/v1/client/img2img/price-calculation Endpoint for calculating price for img2img inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Image Upscale Source: https://docs.deapi.ai/api/v1/transformation/image-upscale openapi-v1.json POST /api/v1/client/img-upscale Endpoint for requesting image upscaling inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug` and check specific **limits**. # Image Upscale Price Calculation Source: https://docs.deapi.ai/api/v1/transformation/image-upscale-price openapi-v1.json POST /api/v1/client/img-upscale/price-calculation Endpoint for calculating price for image upscaling inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Video Upscale Source: https://docs.deapi.ai/api/v1/transformation/video-upscale openapi-v1.json POST /api/v1/client/vid-upscale Endpoint for requesting video upscaling inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Prerequisite:** To ensure a successful request, you must first consult the [Model Selection](/api/v1/utilities/model-selection) endpoint to identify a valid model `slug` and check specific **limits** (including supported `scale` range and maximum input resolution/duration). # Video Upscale Price Calculation Source: https://docs.deapi.ai/api/v1/transformation/video-upscale-price openapi-v1.json POST /api/v1/client/vid-upscale/price-calculation Endpoint for calculating price for video upscaling inference > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Check Balance Source: https://docs.deapi.ai/api/v1/utilities/check-balance openapi-v1.json GET /api/v1/client/balance Endpoint for requesting client current balance. > [!NOTE] > > Requires an **ADMIN** key. An API key gets `403` with `code: insufficient_permissions` — see [API Keys](/api-keys). > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Minimum balance.** Generation requires an account balance of at least **\$0.49**. When your balance drops below this threshold, new jobs are rejected until you top up. This safeguard prevents a single job from costing more than your remaining funds, since the final price of a generation is only known once it completes. Top up your account and generation resumes immediately — no other action is required. # Get Results Source: https://docs.deapi.ai/api/v1/utilities/get-results openapi-v1.json GET /api/v1/client/request-status/{request_id} Check job status and retrieve results via polling > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). > [!NOTE] > > **Consider using webhooks or WebSockets instead of polling.** > > Polling requires repeated API calls and adds latency. For production applications, we recommend: > > * [**Webhooks**](/execution-modes-and-integrations/webhooks) — Results pushed to your server automatically (best for backends) > * [**WebSockets**](/execution-modes-and-integrations/websockets) — Real-time updates with live previews (best for interactive UIs) > > See [Execution Modes](/execution-modes-and-integrations/execution-modes-and-http-queue) for a full comparison. # Model Selection Source: https://docs.deapi.ai/api/v1/utilities/model-selection openapi-v1.json GET /api/v1/client/models Endpoint for fetching all available models. > [!WARNING] > > **API v1 is deprecated.** This version is no longer being developed — new endpoints, parameters and models are added > to v2 only. Use the v2 endpoints to stay current: [v2 API documentation](https://docs.deapi.ai/api/v2/overview). # Get Account Billing Source: https://docs.deapi.ai/api/v2/account/get-account openapi.json GET /api/v2/account Balance and automatic top-up settings. Needs an ADMIN key. > [!NOTE] > > Requires an **ADMIN** key. An API key gets `403` with `code: insufficient_permissions` — see [API Keys](/api-keys). Return the account balance, currency and automatic top-up settings. # List Payments Source: https://docs.deapi.ai/api/v2/account/payments openapi.json GET /api/v2/account/payments Top-ups of the balance, newest first, in every status. Needs an ADMIN key. > [!NOTE] > > Requires an **ADMIN** key. An API key gets `403` with `code: insufficient_permissions` — see [API Keys](/api-keys). List the account's balance top-ups, newest first, in every status. # Get Account Usage Source: https://docs.deapi.ai/api/v2/account/usage openapi.json GET /api/v2/account/usage Cost, requests and errors of every key of the account, optionally per key. The same data as the Usage screen in the Dashboard. Needs an ADMIN key. > [!NOTE] > > Requires an **ADMIN** key. An API key gets `403` with `code: insufficient_permissions` — see [API Keys](/api-keys). Return the cost, number of requests and number of errors of the whole account over a time window — the same data as the Usage screen in the Dashboard. Group the figures by `day`, `hour`, `type`, `model` or `key`. With `group_by=key`, each group's `key` is the id of an existing key, `panel` for jobs started from the Dashboard itself (such as the Playground), `deleted` for all keys that have since been deleted, or `null` when the source of a request is unknown. # Text-to-Music Source: https://docs.deapi.ai/api/v2/audio/music openapi.json POST /api/v2/audio/music Generate music from a text prompt. Generate music tracks from text with control over lyrics, tempo, key, and style. Returns a `request_id` for status polling. > [!NOTE] > > **Prerequisite:** Consult the [Model Selection](/api/v2/utilities/models) endpoint to identify a valid model `slug` and check its parameter limits. Model slugs look like `AceStep_1_5_XL_Turbo_INT8` — always take them from the models endpoint rather than hard-coding a display name. We recommend the XL models: `AceStep_1_5_XL_Turbo_INT8` (fast, 8 steps) and `AceStep_1_5_XL_Base_INT8` (more steps, higher quality). For complete songs with sung vocals, use `MiniMaxMusic3_11B_INT8` (`inference_steps` exactly 30, `guidance_scale` exactly 1.7). > [!NOTE] > > On `MiniMaxMusic3_11B_INT8`, `duration` is a maximum, not a target. The song ends on its own when the lyrics run out, so the file can be much shorter than requested, while the price is always for the requested duration. If the lyrics need more time than `duration` allows, the track is cut off at the limit. ## Field values worth knowing These constraints are enforced by validation and are easy to trip over: | Field | Constraint | | - | - | | `lyrics` | **Required and must be non-empty**, including for instrumental tracks. Omitting it or sending `""` returns `422 The lyrics field is required.` For an instrumental track, send `"[Instrumental]"`. | | `timesignature` | **Integer only**, and only `2`, `3`, `4` or `6` are accepted. A notation string such as `"4/4"` returns `422 The timesignature field must be an integer.` Map the numerator of an x/4 signature (4/4 → `4`, 3/4 → `3`, 2/4 → `2`, 6/8 → `6`); 5/4 and 7/8 cannot be expressed. Omit the field or send an empty value to let the model choose. | | `format` | Use `mp3` — the only format the current models actually produce (`info.limits.output_formats`). `wav` and `flac` are rejected with `422 This output format is not supported by this model. Available formats: mp3.` An unrecognised value such as `ogg` returns `422 The selected format is invalid.` | | `keyscale` | Free-form string (`"C major"`, `"D minor"`, `"F# minor"`). Not validated against a fixed list — passed to the model as a hint. | | `vocal_language` | Free-form string. Both ISO codes (`"en"`) and language names (`"English"`) are accepted. Not validated against a fixed list. | > [!WARNING] > > `timesignature` is validated as an **integer**, not as musical notation. If you populate it from a UI dropdown offering values like `4/4` or `6/8`, convert to the integer before sending — otherwise only the requests that set the field fail, while the rest keep succeeding. # Text-to-Music Price Calculation Source: https://docs.deapi.ai/api/v2/audio/music-price openapi.json POST /api/v2/audio/music/price Estimate the price of a text-to-music generation request. Requires duration and inference_steps parameters. Estimate the cost of a text-to-music job before submitting it. # Text-to-Speech Source: https://docs.deapi.ai/api/v2/audio/speech openapi.json POST /api/v2/audio/speech Generate speech audio from text. Supports three TTS modes: custom_voice (default, preset speakers), voice_clone (clone from reference audio), voice_design (create voice from description). Generate natural-sounding speech from text. Supports preset voices, voice cloning, and voice design depending on the selected model. Returns a `request_id` for status polling. > [!NOTE] > > **Prerequisite:** Consult the [Model Selection](/api/v2/utilities/models) endpoint to identify a valid model `slug` and the per-model voice catalog. > [!TIP] > > **OpenAI SDK users:** This endpoint is also available via the OpenAI-compatible surface as `POST /v1/audio/speech` at `https://oai.deapi.ai/v1`. The six OpenAI voice aliases (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`) are supported on `Kokoro`. See [OpenAI Compatibility](/openai-compatibility). # Text-to-Speech Price Calculation Source: https://docs.deapi.ai/api/v2/audio/speech-price openapi.json POST /api/v2/audio/speech/price Estimate the price of a text-to-speech generation request. Either text or count_text must be provided. Estimate the cost of a text-to-speech job before submitting it. # Audio/Video Transcription Source: https://docs.deapi.ai/api/v2/audio/transcriptions openapi.json POST /api/v2/audio/transcriptions Unified transcription — auto-detects URL or file upload for audio and video sources (YouTube, X, Twitch, Kick, TikTok, X/Twitter Spaces). Unified transcription endpoint that replaces the five v1 endpoints (`vid2txt`, `aud2txt`, `videofile2txt`, `audiofile2txt`, `transcribe`). Accepts URLs or multipart file uploads. Returns a `request_id` for status polling. > [!NOTE] > > Source detection is automatic: pass a public URL in `source_url` (audio and video both use this one field), or upload a file via multipart `source_file`. There are no `video_url` / `audio_url` fields. > [!NOTE] > > **Prerequisite:** Consult the [Model Selection](/api/v2/utilities/models) endpoint to identify a valid model `slug` and check supported languages. > [!TIP] > > **OpenAI SDK users:** This endpoint is also available via the OpenAI-compatible surface as `POST /v1/audio/transcriptions` at `https://oai.deapi.ai/v1`. Maximum file size per upload is **20 MB for audio** and **50 MB for video**, subject to a global **75 MB** request body cap. See [OpenAI Compatibility](/openai-compatibility) and [Limits & Quotas](/limits-and-quotas#file-uploads). `WhisperLargeV3` supports `segment` timestamps only and does not support diarization. `WhisperLargeV3Ct2` adds `word`-level timestamps, per-segment confidence scores and speaker labels — and is the only model that accepts TikTok sources. > [!WARNING] > > **TikTok requires `WhisperLargeV3Ct2`.** A TikTok `source_url` submitted with any other model — `WhisperLargeV3` included — is rejected with `422` before the job is queued, and nothing is charged. Every other source (YouTube, X, Twitch, Kick, X/Twitter Spaces and uploaded files) runs on both models. The same pairing applies to quotes: `platform: "tiktok"` on [`/price`](/api/v2/audio/transcriptions-price) is only valid with `WhisperLargeV3Ct2`. **Segment timestamps are free.** `include_ts: true` with the default `ts_level: "segment"` costs exactly the same as a plain transcription — on every model, `WhisperLargeV3Ct2` included. Only finer granularity is billed: on `WhisperLargeV3Ct2`, `ts_level: "word"` — and `diarize`, which carries the surcharge at *any* granularity, `segment` included — multiplies the duration-based price by 1.5. See [Pricing](/pricing). > [!WARNING] > > **Granularity is validated against the model.** The levels a model accepts are published as `info.limits.timestamp_levels` by [GET /api/v2/models](/api/v2/utilities/models). `WhisperLargeV3` publishes `["segment"]` and `supports_diarization: false`, so `ts_level: "word"` is rejected with `422` and an `errors.ts_level` entry, and `diarize: true` is rejected with `422` and an `errors.diarize` entry. `WhisperLargeV3Ct2` publishes `["segment", "word"]`. Read the model's advertised levels before sending anything other than `segment`. See [Errors](/api/v2/errors). **A source with no speech returns an empty result, not an error.** If the video or audio carries no recognisable words — silence, music only, ambient noise — the job still completes with `status: "done"` and the transcript comes back empty: no segments, no words, no speakers. Treat an empty transcript as a valid outcome and branch on it explicitly, rather than assuming the job failed. A job that genuinely failed reports `status: "error"` with an `error_reason` instead. ## Source metadata Set `include_metadata: true` to have the job-status response carry a `metadata` object describing the source — title, channel, uploader, upload date and engagement counts. > [!WARNING] > > Metadata is a **paid add-on: 0.005 USD per request**. It is charged only on sources that can actually return it, so an uploaded file — which has no source to describe — returns `null` and is never charged. See [Pricing](/pricing). Only URL sources have metadata, and how much you get depends on the platform. The field names are the same either way, and anything a platform does not expose comes back as `null` rather than being omitted. | Metadata | TikTok | YouTube | | - | :-: | :-: | | `id`, `title`, `description`, `channel` | ✅ | ✅ | | `duration_seconds`, `extractor` | ✅ | ✅ | | `view_count`, `like_count` | ✅ | ✅ | | `comment_count` | ✅ | ❌ | | `repost_count`, `save_count` | ✅ | ❌ | | `uploader`, `uploader_url` | ✅ | ❌ | | `channel_id`, `channel_url` | ✅ | ❌ | | `webpage_url` | ✅ | ❌ | | `timestamp`, `upload_date` | ✅ | ❌ | | `thumbnails[]` | ✅ | ❌ | | `fulltitle`, `has_audio`, `is_live` | ✅ | ❌ | | `tags`, `categories`, `chapters`, `heatmap`, `availability`, `channel_follower_count` | ✅\* | ❌ | \* Present in the response schema, but may come back `null` depending on the individual TikTok video. # Transcription Price Calculation Source: https://docs.deapi.ai/api/v2/audio/transcriptions-price openapi.json POST /api/v2/audio/transcriptions/price Estimate the price of a transcription request. Provide one of: source_url, source_file, or duration_seconds. Estimate the cost of an audio/video transcription job before submitting it. Quote from one of three inputs: `source_url`, `source_file`, or a bare `duration_seconds`. > [!WARNING] > > **Pass the same flags you will pass to the job.** `ts_level: "word"`, `diarize` (which implies `include_ts`) and `include_metadata` can all raise the price. A quote that omits them comes in **under** what you are actually charged. `include_ts` on its own does not: segment-level timing is included in the base price. ### Quoting from `duration_seconds` This mode never fetches the source, so it cannot see which platform the media comes from. On models that price per platform — and on TikTok, which is priced from a fixed [length-band card](/pricing) rather than by the hour — pass `platform` alongside the duration: ```bash theme={null} curl -X POST "https://api.deapi.ai/api/v2/audio/transcriptions/price" \ -H "Authorization: Bearer $DEAPI_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "duration_seconds": 240, "platform": "tiktok", "model": "WhisperLargeV3Ct2", "include_ts": true, "ts_level": "word", "include_metadata": true }' ``` Without `platform`, the quote uses the model base rate with no duration-band rounding. > [!NOTE] > > `platform: "tiktok"` is only valid with `model: "WhisperLargeV3Ct2"` — that is the only model that transcribes TikTok. Paired with any other model it is rejected with `422`, the same way the job itself would be. See [Audio/Video Transcription](/api/v2/audio/transcriptions). ## What `WhisperLargeV3Ct2` costs The quote is built in three steps, in this order: 1. **Base amount** — the TikTok [length band](/pricing) for TikTok sources, otherwise the duration rate. 2. **Timestamps** — segment-level timing is included in the base amount, so `include_ts: true` with the default `ts_level: "segment"` does not change the quote. The base amount is multiplied by 1.5 only when `ts_level` is `word`, or when `diarize` is set — diarization carries the surcharge at any granularity, `segment` included. 3. **Metadata** — if `include_metadata` is set on a source that can return it, a flat `0.005` is added *after* the multiplication. # Embeddings Source: https://docs.deapi.ai/api/v2/embeddings/embeddings openapi.json POST /api/v2/embeddings Generate embeddings for one or more input texts. Generate vector embeddings from text for semantic search, clustering, and retrieval-augmented generation (RAG). Returns a `request_id` for status polling. > [!NOTE] > > **Prerequisite:** Consult the [Model Selection](/api/v2/utilities/models) endpoint to identify a valid model `slug` and check its vector dimensionality and maximum input length. > [!TIP] > > **OpenAI SDK users:** This endpoint is also available via the OpenAI-compatible surface as `POST /v1/embeddings` at `https://oai.deapi.ai/v1`. Supports single string and array input, plus `encoding_format: "base64"`. See [OpenAI Compatibility](/openai-compatibility). # Embeddings Price Calculation Source: https://docs.deapi.ai/api/v2/embeddings/embeddings-price openapi.json POST /api/v2/embeddings/price Estimate the price of an embedding request. Estimate the cost of an embedding job before submitting it. # Errors Source: https://docs.deapi.ai/api/v2/errors HTTP status codes and error responses returned by deAPI v2 deAPI uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error from the provided information (e.g., missing required parameter, unauthorized access). Codes in the `5xx` range indicate an error with deAPI servers. ## HTTP Status Codes | Code | Status | Description | | - | - | - | | `200` | OK | Request succeeded. Response contains requested data. | | `401` | Unauthorized | Invalid or missing API key. | | `403` | Forbidden | Account suspended. Returned before validation on endpoints that spend credits; `/price` endpoints are not gated. | | `404` | Not Found | The requested resource (job, route) does not exist. | | `413` | Payload Too Large | Request body exceeded the upload cap. See [Limits & Quotas](/limits-and-quotas#file-uploads). | | `422` | Unprocessable Entity | Request validation failed. Check the `errors` object for details. | | `429` | Too Many Requests | Rate limit exceeded. | | `500` | Internal Server Error | Something went wrong on our end. Try again later. | ## Error Response Format Every error response carries a top-level `message`. Validation errors (`422`) additionally carry an `errors` object: ```json theme={null} { "message": "The selected model does not exist.", "errors": { "model": ["The selected model does not exist."] } } ``` **message** `string` Human-readable error description. Present on every error response. For a `422` with several failures it summarises the first one and counts the rest, e.g. `"The width field must be at least 512. (and 2 more errors)"`. **errors** `object` **Only present on `422`.** A map of `field name → array of messages`, not an array. A single request can fail on several fields at once, and a single field can carry several messages. > [!WARNING] > > The error body has **no `data` and no `statusCode` field** — read the status from the HTTP response itself. Do not iterate `errors` as an array: it is an object keyed by field name (`errors.model[0]`, not `errors[0].field`). ## Error Types ### 401 Unauthorized Returned when authentication fails. **Common causes:** * Missing `Authorization` header * Invalid API key * Expired or revoked API key ```json theme={null} { "message": "Unauthenticated." } ``` **Solution:** Verify your API key is correct and included in the `Authorization: Bearer ` header. *** ### 404 Not Found Returned when the requested resource doesn't exist. Two different bodies are possible. **Unknown job / resource** — e.g. an invalid `request_id` when polling results: ```json theme={null} { "message": "No query results for the requested resource." } ``` > [!NOTE] > > Match on the **status code**, not on the message text. The wording of `404` messages is not part of the API contract and can change. **Unknown route** — e.g. calling a documentation URL instead of the API path: ```json theme={null} { "message": "The route api/v2/utilities/balance could not be found." } ``` **Solution:** Verify the `request_id`, and take API paths from the [API Overview](/api/v2/overview) — documentation URLs such as `/api/v2/utilities/balance` are not API routes (the real one is `/api/v2/account/balance`). > [!NOTE] > > An unknown **model** is not a `404` — it fails validation and returns `422` with `errors.model`. *** ### 422 Unprocessable Entity Returned when request validation fails. `errors` is an object keyed by field name. **Common causes:** * Missing required parameters * Invalid parameter values (out of range, wrong type) * A value outside the selected model's `info.limits` * Invalid image/video URL or format ```json theme={null} { "message": "The width field must be at least 512. (and 2 more errors)", "errors": { "width": ["The width field must be at least 512."], "height": ["The height field must be at least 512."], "steps": ["The steps field must be at least 8."] } } ``` **Solution:** Iterate the keys of the `errors` object to identify which fields failed and correct them. Many limits are model-specific — read `info.limits` from the [Model Selection](/api/v2/utilities/models) endpoint for the model you are calling. *** ### 429 Too Many Requests Returned when you exceed your rate limit. ```json theme={null} { "message": "Too Many Attempts." } ``` Every response carries the current allowance in headers: | Header | Meaning | | - | - | | `X-RateLimit-Limit` | Requests allowed in the current window | | `X-RateLimit-Remaining` | Requests left in the current window | | `X-RateLimit-Source` | Which limit bucket was applied | **Solution:** Back off and retry — see [Limits & Quotas](/limits-and-quotas#rate-limit-errors). *** ### 500 Internal Server Error Returned when an unexpected error occurs on our servers. ```json theme={null} { "message": "Server Error" } ``` **Solution:** Wait a moment and retry your request. If the problem persists, check [status.deapi.ai](https://status.deapi.ai/) or contact support on [Discord](https://discord.com/invite/UFfK5YRBsr). > [!NOTE] > > A job that fails **after** it was accepted does not produce an HTTP error. The submission returns `200` with a `request_id`, and the failure surfaces on the job status as `status: "error"` with `error_code`, `error_reason`, `retryable` and `refunded`. See [Webhooks](/execution-modes-and-integrations/webhooks) for the full value lists. ## Best Practices > [card] Handle all error codes > > Implement error handling for all possible status codes in your application. > [card] Parse the errors object > > For 422 responses, iterate the keys of the `errors` object to display field-specific messages to users. > [card] Implement retry logic > > For 500 errors, implement exponential backoff retry (e.g., 1s, 2s, 4s delays). > [card] Log error responses > > Log full error responses for debugging. Include `request_id` if available. ## Example Error Handling ```python Python theme={null} import requests response = requests.post( "https://api.deapi.ai/api/v2/images/generations", headers={ "Authorization": "Bearer YOUR_API_KEY", "Accept": "application/json" }, json={ "prompt": "a cat", "model": "Flux1schnell", "width": 512, "height": 512, "steps": 4, "guidance": 0, "seed": -1, "loras": [] } ) if response.status_code == 200: data = response.json() request_id = data["data"]["request_id"] print(f"Job started: {request_id}") elif response.status_code == 401: print("Authentication failed. Check your API key.") elif response.status_code == 422: error_data = response.json() print(f"Validation error: {error_data['message']}") # `errors` is an object: field name -> list of messages for field, messages in error_data.get("errors", {}).items(): print(f" Field '{field}': {messages}") elif response.status_code == 429: print("Rate limited. Remaining:", response.headers.get("X-RateLimit-Remaining")) elif response.status_code == 500: print("Server error. Retrying...") else: print(f"Unexpected error: {response.status_code}") ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.deapi.ai/api/v2/images/generations", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", "Accept": "application/json" }, body: JSON.stringify({ prompt: "a cat", model: "Flux1schnell", width: 512, height: 512, steps: 4, guidance: 0, seed: -1, loras: [] }) }); if (response.ok) { const data = await response.json(); const requestId = data.data.request_id; console.log(`Job started: ${requestId}`); } else if (response.status === 401) { console.error("Authentication failed. Check your API key."); } else if (response.status === 422) { const errorData = await response.json(); console.error(`Validation error: ${errorData.message}`); // `errors` is an object: field name -> array of messages for (const [field, messages] of Object.entries(errorData.errors ?? {})) { console.error(` Field '${field}': ${messages.join(", ")}`); } } else if (response.status === 429) { console.error("Rate limited. Remaining:", response.headers.get("X-RateLimit-Remaining")); } else if (response.status === 500) { console.error("Server error. Retrying..."); } else { console.error(`Unexpected error: ${response.status}`); } ``` # Image Background Removal Source: https://docs.deapi.ai/api/v2/images/background-removals openapi.json POST /api/v2/images/background-removals Remove the background from an image. Remove the background from an image, producing a transparent PNG output. Returns a `request_id` for status polling. > [!NOTE] > > **Prerequisite:** Consult the [Model Selection](/api/v2/utilities/models) endpoint to identify a valid model `slug`. # Image Background Removal Price Calculation Source: https://docs.deapi.ai/api/v2/images/background-removals-price openapi.json POST /api/v2/images/background-removals/price Estimate the price of an image background removal request. Estimate the cost of an image background removal job before submitting it. # Image Edit Source: https://docs.deapi.ai/api/v2/images/edits openapi.json POST /api/v2/images/edits Edit an image guided by a text prompt. Accepts either a single image via "image" or multiple images via "images[]" (mutually exclusive). Image Edit transforms an existing image based on a text prompt (image-to-image). Returns a `request_id` for status polling. > [!NOTE] > > **Prerequisite:** Consult the [Model Selection](/api/v2/utilities/models) endpoint to identify a valid model `slug` and check specific **limits**. > [!TIP] > > **OpenAI SDK users:** This endpoint is also available via the OpenAI-compatible surface as `POST /v1/images/edits` at `https://oai.deapi.ai/v1`. Inpainting (`mask` parameter) is not supported. See [OpenAI Compatibility](/openai-compatibility). # Image Edit Price Calculation Source: https://docs.deapi.ai/api/v2/images/edits-price openapi.json POST /api/v2/images/edits/price Estimate the price of an image edit request. Estimate the cost of an image edit job before submitting it. # Image Generation Source: https://docs.deapi.ai/api/v2/images/generations openapi.json POST /api/v2/images/generations Generate an image from a text prompt. Image Generation creates images from text prompts using AI diffusion models. The endpoint returns a `request_id` you can poll via `GET /api/v2/jobs/{request_id}` or receive via webhooks / WebSockets. > [!NOTE] > > **Prerequisite:** Consult the [Model Selection](/api/v2/utilities/models) endpoint to identify a valid model `slug`, check specific **limits** and **features**, and verify **LoRA** availability. Please **omit** the LoRA parameter by default during initial testing. > [!TIP] > > **OpenAI SDK users:** This endpoint is also available via the OpenAI-compatible surface as `POST /v1/images/generations` at `https://oai.deapi.ai/v1`. See [OpenAI Compatibility](/openai-compatibility). # Image Generation Price Calculation Source: https://docs.deapi.ai/api/v2/images/generations-price openapi.json POST /api/v2/images/generations/price Estimate the price of a text-to-image generation request. Estimate the cost of an image generation job before submitting it. Request body mirrors the fields used by `/api/v2/images/generations`. # Image OCR Source: https://docs.deapi.ai/api/v2/images/ocr openapi.json POST /api/v2/images/ocr Extract text from an image via OCR. Extract text from images (Optical Character Recognition). Returns a `request_id` for status polling. > [!NOTE] > > **Prerequisite:** Consult the [Model Selection](/api/v2/utilities/models) endpoint to identify a valid model `slug`. # Image OCR Price Calculation Source: https://docs.deapi.ai/api/v2/images/ocr-price openapi.json POST /api/v2/images/ocr/price Estimate the price of an image OCR request. Estimate the cost of an OCR job before submitting it. # Image Upscale Source: https://docs.deapi.ai/api/v2/images/upscales openapi.json POST /api/v2/images/upscales Upscale an image to a higher resolution. Increase the resolution of an image using AI super-resolution. Returns a `request_id` for status polling. > [!NOTE] > > **Prerequisite:** Consult the [Model Selection](/api/v2/utilities/models) endpoint to identify a valid model `slug` and check specific **limits** (including supported `scale` range and maximum input resolution). # Image Upscale Price Calculation Source: https://docs.deapi.ai/api/v2/images/upscales-price openapi.json POST /api/v2/images/upscales/price Estimate the price of an image upscale request. Estimate the cost of an image upscale job before submitting it. # Create Key Source: https://docs.deapi.ai/api/v2/keys/create-key openapi.json POST /api/v2/keys Creates a key with the API role. Needs an ADMIN key; ADMIN keys can only be created in the Dashboard. **The secret is returned once, in this response.** Counts toward the account's limit of active keys and the hourly limit of keys created over the API (shared by all ADMIN keys of the account). An `ip_whitelist` given here applies from the key's first call. > [!NOTE] > > Requires an **ADMIN** key. An API key gets `403` with `code: insufficient_permissions` — see [API Keys](/api-keys). Create a new **API** key, optionally with an expiration date, spend limit, reset window and IP allowlist. ADMIN keys can only be created in the Dashboard. > [!WARNING] > > The `secret` is returned **only once**, in the response to this call. Store it straight away — it cannot be read again. If it is lost, create a new key and delete the old one. Keys created over the API count toward the account limit of [100 active keys](/api-keys#number-of-keys). Creating keys is also rate-limited per account: too many in an hour returns `429` with `X-RateLimit-Type: key-creation`. # Delete Key Source: https://docs.deapi.ai/api/v2/keys/delete-key openapi.json DELETE /api/v2/keys/{id} Permanently deletes an API-role key. Needs an ADMIN key; ADMIN keys are deleted in the Dashboard only. The key's past usage stays in usage reports. > [!NOTE] > > Requires an **ADMIN** key. An API key gets `403` with `code: insufficient_permissions` — see [API Keys](/api-keys). Permanently delete an API key. The key stops working immediately and frees its slot. Its past usage stays in usage reports, grouped as `deleted` in [Get Account Usage](/api/v2/account/usage). ADMIN keys can be deleted only in the Dashboard. # Get Current Key Source: https://docs.deapi.ai/api/v2/keys/get-current-key openapi.json GET /api/v2/key The key sending the request: name, preview, role, status, dates, spend limit and IP whitelist. Never the secret. Works with any key role. > [!NOTE] > > Works with both **ADMIN** and **API** keys — see [API Keys](/api-keys). Return the key that sent the request: its name, role, status, expiration date, spend limit with what is left in the current window, and IP allowlist. The secret is never returned. Use it to check how much of the limit is left, or when it resets, before sending a job. # Get Current Key Usage Source: https://docs.deapi.ai/api/v2/keys/get-current-key-usage openapi.json GET /api/v2/key/usage Cost, requests and errors of the key sending the request. Works with any key role. > [!NOTE] > > Works with both **ADMIN** and **API** keys — see [API Keys](/api-keys). Return the cost, number of requests and number of errors of the key that sent the request, over a time window. Group the figures by `day`, `hour`, `type` or `model`. The report shows nothing about other keys or the account balance. # Get Key Source: https://docs.deapi.ai/api/v2/keys/get-key openapi.json GET /api/v2/keys/{id} Any key of the account. Needs an ADMIN key. > [!NOTE] > > Requires an **ADMIN** key. An API key gets `403` with `code: insufficient_permissions` — see [API Keys](/api-keys). Return one key of the account by its id — the same fields as [Get Current Key](/api/v2/keys/get-current-key). # Get Key Usage Source: https://docs.deapi.ai/api/v2/keys/get-key-usage openapi.json GET /api/v2/keys/{id}/usage Like `GET /api/v2/key/usage`, for any key of the account. Needs an ADMIN key. > [!NOTE] > > Requires an **ADMIN** key. An API key gets `403` with `code: insufficient_permissions` — see [API Keys](/api-keys). Return the cost, number of requests and number of errors of any key of the account, over a time window — the same report as [Get Current Key Usage](/api/v2/keys/get-current-key-usage). # List Keys Source: https://docs.deapi.ai/api/v2/keys/list-keys openapi.json GET /api/v2/keys Every key of the account, newest first. Needs an ADMIN key. Never secrets. > [!NOTE] > > Requires an **ADMIN** key. An API key gets `403` with `code: insufficient_permissions` — see [API Keys](/api-keys). List every key of the account, newest first, with its role, status, spend limit, usage in the current window and IP allowlist. Secrets are never returned. # Update Key Source: https://docs.deapi.ai/api/v2/keys/update-key openapi.json PATCH /api/v2/keys/{id} Switches an API-role key on or off, changes its expiry date, spend limit and reset window, and sets the addresses it may be used from. Needs an ADMIN key. The role cannot be changed; ADMIN keys are changed in the Dashboard only. Making a key active again counts toward the limit of active keys. > [!NOTE] > > Requires an **ADMIN** key. An API key gets `403` with `code: insufficient_permissions` — see [API Keys](/api-keys). Disable or re-enable an API key, or change its expiration date, spend limit, reset window or IP allowlist. Send only the fields you want to change. The role cannot be changed, and ADMIN keys can be changed only in the Dashboard. Changes apply from the next request. Changing the spend limit does not reset the counter; changing the reset window does. # API Overview Source: https://docs.deapi.ai/api/v2/overview Complete reference of all deAPI v2 endpoints All endpoints use base URL `https://api.deapi.ai` and require authentication via `Authorization: Bearer ` header. > [!NOTE] > > Each POST endpoint has a corresponding `/price` endpoint to estimate costs before execution. > [!TIP] > > **OpenAI SDK users:** deAPI also exposes an OpenAI-compatible surface at `https://oai.deapi.ai/v1` for image generation, TTS, transcription, embeddings, and video. See [OpenAI Compatibility](/openai-compatibility) for a drop-in migration guide. ## Images | Method | Endpoint | Description | Docs | | - | - | - | - | | `POST` | `/api/v2/images/generations` | Generate image from text prompt | [→](/api/v2/images/generations) | | `POST` | `/api/v2/images/generations/price` | Calculate image generation price | [→](/api/v2/images/generations-price) | | `POST` | `/api/v2/images/edits` | Edit/transform an image | [→](/api/v2/images/edits) | | `POST` | `/api/v2/images/edits/price` | Calculate image edit price | [→](/api/v2/images/edits-price) | | `POST` | `/api/v2/images/ocr` | Extract text from image (OCR) | [→](/api/v2/images/ocr) | | `POST` | `/api/v2/images/ocr/price` | Calculate OCR price | [→](/api/v2/images/ocr-price) | | `POST` | `/api/v2/images/background-removals` | Remove image background | [→](/api/v2/images/background-removals) | | `POST` | `/api/v2/images/background-removals/price` | Calculate bg removal price | [→](/api/v2/images/background-removals-price) | | `POST` | `/api/v2/images/upscales` | Upscale image resolution | [→](/api/v2/images/upscales) | | `POST` | `/api/v2/images/upscales/price` | Calculate image upscale price | [→](/api/v2/images/upscales-price) | ## Videos | Method | Endpoint | Description | Docs | | - | - | - | - | | `POST` | `/api/v2/videos/generations` | Generate video from text prompt | [→](/api/v2/videos/generations) | | `POST` | `/api/v2/videos/generations/price` | Calculate video generation price | [→](/api/v2/videos/generations-price) | | `POST` | `/api/v2/videos/animations` | Animate image into video | [→](/api/v2/videos/animations) | | `POST` | `/api/v2/videos/animations/price` | Calculate animation price | [→](/api/v2/videos/animations-price) | | `POST` | `/api/v2/videos/audio-syncs` | Generate video from audio + prompt | [→](/api/v2/videos/audio-syncs) | | `POST` | `/api/v2/videos/audio-syncs/price` | Calculate audio-sync price | [→](/api/v2/videos/audio-syncs-price) | | `POST` | `/api/v2/videos/upscales` | Upscale video resolution | [→](/api/v2/videos/upscales) | | `POST` | `/api/v2/videos/upscales/price` | Calculate video upscale price | [→](/api/v2/videos/upscales-price) | | `POST` | `/api/v2/videos/descriptions` | Describe visible events in a video | [→](/api/v2/videos/descriptions) | | `POST` | `/api/v2/videos/descriptions/price` | Calculate video description price | [→](/api/v2/videos/descriptions-price) | ## Audio | Method | Endpoint | Description | Docs | | - | - | - | - | | `POST` | `/api/v2/audio/speech` | Generate speech from text (TTS) | [→](/api/v2/audio/speech) | | `POST` | `/api/v2/audio/speech/price` | Calculate TTS price | [→](/api/v2/audio/speech-price) | | `POST` | `/api/v2/audio/music` | Generate music from text | [→](/api/v2/audio/music) | | `POST` | `/api/v2/audio/music/price` | Calculate music price | [→](/api/v2/audio/music-price) | | `POST` | `/api/v2/audio/transcriptions` | Transcribe audio/video (unified) | [→](/api/v2/audio/transcriptions) | | `POST` | `/api/v2/audio/transcriptions/price` | Calculate transcription price | [→](/api/v2/audio/transcriptions-price) | ## Embeddings | Method | Endpoint | Description | Docs | | - | - | - | - | | `POST` | `/api/v2/embeddings` | Generate text embeddings | [→](/api/v2/embeddings/embeddings) | | `POST` | `/api/v2/embeddings/price` | Calculate embedding price | [→](/api/v2/embeddings/embeddings-price) | ## Prompt Enhancement AI-powered prompt boosters. In v2 all boosters use a single unified endpoint — select the booster with the `type` field (dot notation) and the target model via `model_slug`. | Method | Endpoint | Description | Docs | | - | - | - | - | | `POST` | `/api/v2/prompts/enhancements` | Prompt booster (all types) | [→](/api/v2/prompt-enhancement/prompt-booster) | | `POST` | `/api/v2/prompts/enhancements/price` | Prompt booster price | [→](/api/v2/prompt-enhancement/prompt-booster-price) | ## Utilities | Method | Endpoint | Description | Docs | | - | - | - | - | | `GET` | `/api/v2/account/balance` | Get current account balance | [→](/api/v2/utilities/balance) | | `GET` | `/api/v2/jobs/{job_request}` | Check job status and get results | [→](/api/v2/utilities/jobs) | | `GET` | `/api/v2/models` | List available models — send `?limit=50` for the full list | [→](/api/v2/utilities/models) | > [!WARNING] > > **Call the path in the "Endpoint" column, not the documentation URL.** The links in the "Docs" column are addresses on this documentation site and are grouped by topic — `/api/v2/utilities/balance`, `/api/v2/utilities/models`, `/api/v2/utilities/jobs` and `/api/v2/audio/music-price` are page URLs, not API routes, and calling them against `api.deapi.ai` returns `404 The route ... could not be found.` The real routes are `/api/v2/account/balance`, `/api/v2/models`, `/api/v2/jobs/{job_request}` and `/api/v2/audio/music/price`. ## Workflow Typical API usage follows this pattern: **1. Check available models** Call `GET /api/v2/models?limit=50` to get current models and their parameters. That covers the whole catalogue in one call — the page size defaults to 50, and `meta.last_page` reading `1` is what confirms nothing is missing. **2. Calculate price (optional)** Call the `/price` endpoint with your parameters to estimate cost. **3. Submit job** Call the main endpoint (e.g., `POST /api/v2/images/generations`). Response contains `request_id`. **4. Poll or receive via webhook** Call `GET /api/v2/jobs/{request_id}` or use webhooks / WebSockets for push updates. **5. Download result** When `status` is `done`, use `result_url` to download your generated content. ## Response Formats ```json Job Submission (generations, edits, etc.) theme={null} { "data": { "request_id": "c08a339c-73e5-4d67-a4d5-231302fbff9a" } } ``` ```json Job Status (GET /api/v2/jobs/{id}) theme={null} { "data": { "status": "done", "progress": 100.0, "result_url": "https://...", "results_alt_formats": null, "result": null, "preview": null } } ``` ```json Balance theme={null} { "data": { "balance": 19.72 } } ``` ```json Models List (GET /api/v2/models?limit=50) theme={null} { "data": [ { "name": "FLUX.1 Schnell 12B NF4", "slug": "Flux1schnell", "inference_types": ["txt2img"], "tags": [], "status": "standard_model", "info": { } } ], "links": { "first": "https://api.deapi.ai/api/v2/models?page=1", "last": "https://api.deapi.ai/api/v2/models?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 30 } } ``` ```json Error (4xx/5xx) theme={null} { "message": "The selected model does not exist.", "errors": { "model": ["The selected model does not exist."] } } ``` > [!NOTE] > > Response structure varies by endpoint. See individual endpoint documentation for exact schemas. See [Errors](/api/v2/errors) for detailed error handling documentation. # Prompt Enhancement - Overview Source: https://docs.deapi.ai/api/v2/prompt-enhancement/overview AI-powered prompt optimization tools for better generation results. > [!NOTE] > > In v2 all prompt boosters use a **single unified endpoint** — `POST /api/v2/prompts/enhancements`. You select the booster with the **`type`** field (v2 dot notation) and the target model via **`model_slug`**. ## Endpoints | Purpose | Endpoint | | - | - | | Prompt Booster | `POST /api/v2/prompts/enhancements` | | Booster Price | `POST /api/v2/prompts/enhancements/price` | ## Request fields (`/api/v2/prompts/enhancements`) | Field | Required | Notes | | - | - | - | | `prompt` | **Yes** | Raw user prompt (min 3 chars). | | `type` | **Yes** | Inference type in dot notation (see table below). | | `model_slug` | **Yes** | Target deAPI model, e.g. `Flux_2_Klein_4B_BF16`. Selects the guide. | | `image` | Conditional — required for `images.edits` / `videos.animations` | Reference image: URL, data-URI, base64, or file. | | `negative_prompt` | No | Optional (min 3 chars). | ### `type` values Only prompt-driven inference types have a booster. Types that take no meaningful prompt — upscaling, background removal, OCR, transcription, embeddings — are not supported and are rejected with **422**. | `type` | Use case | | - | - | | `images.generations` | Text-to-image | | `images.edits` | Image-to-image / edit (requires `image`) | | `videos.generations` | Text/image-to-video | | `videos.animations` | Character animation (requires `image`) | | `audio.speech` | Text-to-speech | | `audio.music` | Text-to-music | ## Workflow **1. Enhance your prompt** Call `POST /api/v2/prompts/enhancements` with `prompt`, `type`, and `model_slug` (plus `image` for `images.edits` / `videos.animations`). **2. Use the enhanced prompt** Plug the returned `prompt` into the matching v2 generation endpoint — `/api/v2/images/generations`, `/api/v2/images/edits`, `/api/v2/videos/generations`, `/api/v2/audio/speech`, etc. See the [Prompt Booster](/api/v2/prompt-enhancement/prompt-booster) page for the full request/response schema. ## Inline boosting (`enhance_prompt`) Instead of calling the booster first and passing the result on yourself, you can set **`enhance_prompt: true`** directly on a generation request. The boost then runs as an async pre-step inside the job, and the boosted prompt is what gets generated. Supported on `POST /api/v2/images/generations`, `POST /api/v2/images/edits`, `POST /api/v2/videos/generations` and `POST /api/v2/videos/animations`. | | Two-step (`/prompts/enhancements`) | Inline (`enhance_prompt: true`) | | - | - | - | | Round trips | Two | One | | You see the boosted prompt before generating | Yes | No — it comes back on the job | | Billing | Boost billed separately | Boost fee billed on the job | The job status response reports what happened: * `prompt_boosted` — whether the boost actually ran. * `prompt_boost` — the boosted and original prompts. Non-null only once `prompt_boosted` is true; it stays `null` while the boost is still queued, and when no boost was requested. > [!WARNING] > > Inline boosting requires a prompt-booster guide configured for the target model. The request is rejected with **422** if no guide exists for that model, or if your account balance cannot cover the boost fee on top of the generation. # Prompt Booster Source: https://docs.deapi.ai/api/v2/prompt-enhancement/prompt-booster openapi.json POST /api/v2/prompts/enhancements Rewrites a prompt for a specific model using a guide configured for that model and inference type. Requires a guide for your `model_slug` + `type` pair — call the `/price` sibling first, which runs the same check for free and quotes the fee. Enhance a raw user prompt into a detailed, model-friendly prompt using the AI guide that matches the **target model** and **inference type**. * Set **`type`** (v2 dot notation) and **`model_slug`** to pick the right guide. * For **`images.edits`** and **`videos.animations`**, also send the source **`image`** (URL, data-URI, base64, or file). * Synchronous — the enhanced prompt is returned directly in the response body (`{ prompt, negative_prompt }`). > [!NOTE] > > Required fields: `prompt`, `type`, `model_slug` (plus `image` for `images.edits` / `videos.animations`). The returned `negative_prompt` is provided for compatibility and is ignored by models that do not support negative prompts (e.g. FLUX.2 Klein). ### Accepted `type` values `images.generations`, `images.edits`, `videos.generations`, `videos.animations`, `audio.speech`, `audio.music` Only prompt-driven inference types have a booster. Upscaling, background removal, OCR, transcription and embeddings are not supported and are rejected with **422**. ### Example (image-to-image) ```bash theme={null} curl -X POST "https://api.deapi.ai/api/v2/prompts/enhancements" \ -H "Authorization: Bearer " \ -F "prompt=Make it look like a digital photo" \ -F "type=images.edits" \ -F "model_slug=Flux_2_Klein_4B_BF16" \ -F "image=@source.jpg" ``` Then send the returned `prompt` to the matching generation endpoint (e.g. `POST /api/v2/images/edits`). # Prompt Booster Price Source: https://docs.deapi.ai/api/v2/prompt-enhancement/prompt-booster-price openapi.json POST /api/v2/prompts/enhancements/price Price of a prompt boost, and a free check that one is possible: it runs the same guide lookup as the boost itself, so a 422 here means the boost would also be rejected. Charges nothing either way. NOTE the response shape differs from every other price endpoint: this one returns `{"price": …}` at the top level, not wrapped in `data`. Calculate the cost of a prompt-booster call before running it. Takes the same fields as the [Prompt Booster](/api/v2/prompt-enhancement/prompt-booster) (`prompt`, `type`, `model_slug`, optional `image` / `negative_prompt`) and returns `{ "price": }`. # Check Balance Source: https://docs.deapi.ai/api/v2/utilities/balance openapi.json GET /api/v2/account/balance Retrieve the current account balance for the authenticated client. Needs an ADMIN key. > [!NOTE] > > Requires an **ADMIN** key. An API key gets `403` with `code: insufficient_permissions` — see [API Keys](/api-keys). Retrieve the current account balance (in USD) for the authenticated API key. Useful for displaying usage in dashboards or gating background jobs when funds run low. > [!NOTE] > > **Minimum balance.** Generation requires an account balance of at least **\$0.49**. When your balance drops below this threshold, new jobs are rejected until you top up. This safeguard prevents a single job from costing more than your remaining funds, since the final price of a generation is only known once it completes. Top up your account and generation resumes immediately — no other action is required. # Get Job Results Source: https://docs.deapi.ai/api/v2/utilities/jobs openapi.json GET /api/v2/jobs/{job_request} Retrieve the current status and result of a submitted inference job. Retrieve the current status and result of a submitted inference job. Use the `request_id` returned by any `POST /api/v2/**` endpoint. > [!NOTE] > > **Consider using webhooks or WebSockets instead of polling.** > > * **[Webhooks](/execution-modes-and-integrations/webhooks)** — Results pushed to your server automatically > * **[WebSockets](/execution-modes-and-integrations/websockets)** — Real-time updates with live previews > > See [Execution Modes](/execution-modes-and-integrations/execution-modes-and-http-queue) for full comparison. # Model Selection Source: https://docs.deapi.ai/api/v2/utilities/models openapi.json GET /api/v2/models Lists the inference models available to your account. The list is scoped to you: it contains only enabled models that are either public or explicitly granted to your account, and it omits models that require a higher plan tier than your account has (those return 422 on generation and pricing). A model explicitly granted to your account is always listed, whatever tier it requires. List every available model with `slug`, supported `inference_types`, per-model limits (resolution, duration, steps), and feature flags (e.g., LoRA support). For [Video Animation](/api/v2/videos/animations), check `info.features.supports_image_refs`, `supports_video_refs`, and `supports_audio_refs` independently. Models advertising reference support publish effective `info.limits` for reference counts (`max_ref_images`, `max_ref_videos`, `max_ref_audios`, `max_ref_files`), video/audio duration (`min_ref_video_duration`, `max_ref_video_duration`, `min_ref_audio_duration`, `max_ref_audio_duration`), and image aspect ratio (`min_ref_image_ratio`, `max_ref_image_ratio`). An unsupported reference type has a count limit of `0`. > [!TIP] > > Call `GET /api/v2/models?limit=50` once at session start, cache the result, and use the returned `slug` values in your generation/edit requests. Filter with `&filter[inference_types]=txt2img` to narrow results by task. > [!WARNING] > > **Send `limit=50` and check `meta.last_page`.** The page size defaults to 50, and a value above the maximum is clamped down, not rejected. `limit=50` covers the current catalogue in one call, and `meta.last_page` reading `1` is what confirms the `data` array is complete; nothing else in the response distinguishes a partial page from a full one. # Video Animation (Image-to-Video) Source: https://docs.deapi.ai/api/v2/videos/animations openapi.json POST /api/v2/videos/animations Animate a still image into a video. Animate a still image or generate a video from reference images, videos, and audio on supported models. Returns a `request_id` for status polling. > [!NOTE] > > **Prerequisite:** Consult the [Model Selection](/api/v2/utilities/models) endpoint to identify a valid model `slug` and check specific **limits**. ## Input modes * **Keyframes:** Upload `first_frame_image` and, if the model supports it, `last_frame_image`. Images are fitted to the generation canvas and may have any aspect ratio. * **Full-reference mode:** Upload `ref_images` and/or `ref_videos`, with optional `ref_audios`. Do not combine references with `first_frame_image` or `last_frame_image`. Audio cannot be the only reference. Check `info.features.supports_image_refs`, `supports_video_refs`, and `supports_audio_refs` separately. Support for one reference type does not imply support for the others. ## Reference order & prompt labels Send reference files as ordered multipart arrays. Explicit indices must start at `0` with no gaps, for example `ref_images[0]`, `ref_images[1]`. | Input | Prompt label | | - | - | | `ref_images[0]`, `ref_images[1]` | ``, `` | | `ref_videos[0]` | `