### POST /api/v1/videos Source: https://genmagic.co/openapi.json Returns 202 immediately with { id, object: "video.generation", model, status: "queued", created (Unix seconds), status_url }; nothing is charged until the clip completes. Poll GET /api/v1/videos/{id} until status is completed or failed. Also OpenAI's Videos API: a multipart request (what the OpenAI SDKs' client.videos.create sends) or one with seconds, size or input_reference is answered with OpenAI's Video object, an id starting video_, at HTTP 200, so code written for Sora 2's Videos API runs unchanged with a GenMagic model id; a request that still names sora-2 runs on google/veo-3.1-fast and sora-2-pro on google/veo-3.1 (the answer's model says which ran). ```markdown ### Request Body **Content-Type:** application/json - **prompt** (string) (required): Description of the video. - **model** (string): Model id. Omit for the default. Must be a text-to-video model (capabilities.text_to_video in GET /api/v1/models?category=video); a model that edits, upscales or animates supplied media is refused with 400 model_not_supported. - **aspect_ratio** (string (16:9|9:16|1:1)): Defaults to the opening image's shape when `image` is portrait (9:16) or landscape (16:9), otherwise 16:9. ("16:9"|"9:16"|"1:1") - **duration** (integer): Clip length in seconds, one of the model's pricing.video.durations_seconds in GET /api/v1/models?category=video. Omit for the model's default (usually 5). The price scales with it. - **resolution** (string): One of the model's pricing.video.resolutions, for example 720p. Omit for the model's default. The price scales with it: pricing.video.usd_per_second lists the rate at each resolution. - **generate_audio** (boolean): Whether to add sound, for a model whose pricing.video.audio_supported is true. Omit for the model's default; sound can roughly double the price (pricing.video.usd_per_second_with_audio). A model with pricing.video.audio_always true makes sound on every clip and has no switch. - **image** (string): Image-to-video: an https URL or data:image URL the clip opens on; the prompt then describes the motion. For a model whose capabilities.frame_images includes first_frame (400 model_not_supported otherwise, 400 invalid_image for an unusable image). Most models bill it like text-to-video; where one does not, its pricing.video carries image_to_video_usd_per_second (a rate of its own) or image_input_usd (a fee for each image supplied). - **last_frame** (string): An https URL or data:image URL the clip ends on, for a model whose capabilities.frame_images includes last_frame. - **references** (array (string)): Reference-to-video: up to 9 https URLs or data:image URLs of characters, objects or a look the clip keeps consistent, none of them a frame of it. Name what each shows in the prompt ("the doctor from the first reference walks through the door from the second"). Not combined with image or last_frame (400 invalid_image). Models made for it have capabilities.references true; each image may carry the model's image_input_usd. - **seconds** (string): OpenAI Videos API form of duration ("8"). duration wins when both are sent; the model's own lengths apply as for duration. - **size** (string): OpenAI Videos API form of aspect_ratio and resolution, width x height ("1280x720" is 16:9 at 720p, "720x1280" 9:16, "1792x1024" 16:9 at 1080p). aspect_ratio and resolution win when sent. - **input_reference** (string): OpenAI Videos API form of image: an uploaded image file (multipart), an https or data:image URL, or { "image_url": "..." }. An OpenAI file_id cannot be read and is refused (400 invalid_image). ### Responses #### 202 - Accepted: async job created. Empty response body #### 401 - authentication_error: missing or invalid API key. authentication_error: missing or invalid API key. #### 402 - insufficient_quota: credit balance would go negative. insufficient_quota: credit balance would go negative. #### 429 - rate_limit_error: over 300 requests/minute for this key. rate_limit_error: over 300 requests/minute for this key. ### Example Usage ```bash curl -X POST "https://genmagic.co/api/v1/videos" \ -H "Content-Type: application/json" \ -d '{ "prompt": "string", "model": "string", "aspect_ratio": "16:9", "duration": "0", "resolution": "string", "generate_audio": "true", "image": "string", "last_frame": "string", "references": [ "string" ], "seconds": "string", "size": "string", "input_reference": "string" }' ``` ``` -------------------------------- ### GET /api/v1/videos/{id} Source: https://genmagic.co/openapi.json Returns { id, object, model, status } with status queued or processing while the clip renders; when completed it adds the durable hosted url and cost_cents. A render failure is a terminal failed status at HTTP 200 with error, a plain-text message. Charged once, on completion. An id starting video_ (from an OpenAI-style create) is answered with OpenAI's Video object instead: status queued, in_progress, completed or failed, progress, created_at, and error as { code, message }. This is a lookup and spends no credits. ```markdown ### Parameters - **id** (string, path, required): The job id from POST /api/v1/videos. ### Responses #### 200 - Success. Empty response body #### 401 - authentication_error: missing or invalid API key. authentication_error: missing or invalid API key. #### 429 - rate_limit_error: over 300 requests/minute for this key. rate_limit_error: over 300 requests/minute for this key. ### Example Usage ```bash curl -X GET "https://genmagic.co/api/v1/videos/{id}" ``` ``` -------------------------------- ### GET /api/v1/models Source: https://genmagic.co/openapi.json OpenAI-compatible model list enriched with capabilities, pricing, and benchmarks from the same live catalog the studio uses, newest first (by created, a Unix timestamp in seconds). Text models also carry supported_parameters, capabilities.reasoning_efforts and reasoning_mandatory, and cache, reasoning and long-context (tiers) prices where the model publishes them; audio models carry audio_kind (speech or music), the endpoint that runs them. A pure lookup: spends no credits, and works without a key. This is a lookup and spends no credits. ```markdown ### Parameters - **category** (string (text|image|audio|video), query, optional): Filter by output category. - **capability** (string (reasoning|vision|tools|structured), query, optional): Filter by capability. - **search** (string, query, optional): Substring of a model id or name. ### Responses #### 200 - Success. Empty response body #### 401 - authentication_error: invalid API key (a request without a key is answered anonymously). authentication_error: invalid API key (a request without a key is answered anonymously). #### 429 - rate_limit_error: over 300 requests/minute for this key. rate_limit_error: over 300 requests/minute for this key. ### Example Usage ```bash curl -X GET "https://genmagic.co/api/v1/models?category=text&capability=reasoning&search=string" ``` ``` -------------------------------- ### GET /api/v1/benchmarks Source: https://genmagic.co/openapi.json Every benchmark in the matrix, described identically (what it tests, metric, status, maintainer, source). A pure lookup: spends no credits. Each links to /api/v1/benchmarks/{id} for its model leaderboard. This is a lookup and spends no credits. ```markdown ### Parameters - **category** (string (reasoning|math|coding|agentic|chat|multimodal|long-context|composite), query, optional): Filter by benchmark category. ### Responses #### 200 - Success. Empty response body #### 401 - authentication_error: missing or invalid API key. authentication_error: missing or invalid API key. #### 429 - rate_limit_error: over 300 requests/minute for this key. rate_limit_error: over 300 requests/minute for this key. ### Example Usage ```bash curl -X GET "https://genmagic.co/api/v1/benchmarks?category=reasoning" ``` ``` -------------------------------- ### GET /api/v1/videos/{id}/content Source: https://genmagic.co/openapi.json OpenAI's Videos API download (client.videos.download_content): redirects (302) to the finished clip's durable file. 409 video_not_ready while it renders, 409 video_failed for a failed job. Only the clip exists: variant=thumbnail or spritesheet answers 404. Works with either id form. This is a lookup and spends no credits. ```markdown ### Parameters - **id** (string, path, required): The job id from POST /api/v1/videos (with or without the video_ prefix). ### Responses #### 200 - Success. Empty response body #### 401 - authentication_error: missing or invalid API key. authentication_error: missing or invalid API key. #### 429 - rate_limit_error: over 300 requests/minute for this key. rate_limit_error: over 300 requests/minute for this key. ### Example Usage ```bash curl -X GET "https://genmagic.co/api/v1/videos/{id}/content" ``` ``` -------------------------------- ### GET /api/v1/usage Source: https://genmagic.co/openapi.json Returns the authenticated key owner's live balance and lifetime spend so a program can check budget before a run. Spends no credits. This is a lookup and spends no credits. ```markdown ### Responses #### 200 - Success. Empty response body #### 401 - authentication_error: missing or invalid API key. authentication_error: missing or invalid API key. #### 429 - rate_limit_error: over 300 requests/minute for this key. rate_limit_error: over 300 requests/minute for this key. ### Example Usage ```bash curl -X GET "https://genmagic.co/api/v1/usage" ``` ``` -------------------------------- ### API Overview: GenMagic API Source: https://genmagic.co/openapi.json GenMagic is one studio for every generative AI model. Turn a single prompt into text, images, video, audio, music, or code, and route it to the best model automatically. New models the day they launch. OpenAI-compatible REST API plus a remote Model Context Protocol server at /api/mcp (Streamable HTTP, protocol 2025-06-18). Authenticate with an API key minted at https://genmagic.co/get-api-key; the model catalog (GET /api/v1/models) also answers without one. Billed pay-as-you-go against a prepaid USD balance; cost and remaining balance are returned in response headers. ```yaml # GenMagic API # Version: 1.0.0 GenMagic is one studio for every generative AI model. Turn a single prompt into text, images, video, audio, music, or code, and route it to the best model automatically. New models the day they launch. OpenAI-compatible REST API plus a remote Model Context Protocol server at /api/mcp (Streamable HTTP, protocol 2025-06-18). Authenticate with an API key minted at https://genmagic.co/get-api-key; the model catalog (GET /api/v1/models) also answers without one. Billed pay-as-you-go against a prepaid USD balance; cost and remaining balance are returned in response headers. # Base URL: https://genmagic.co ``` -------------------------------- ### GET /api/v1/models/{id} Source: https://genmagic.co/openapi.json OpenAI-compatible client.models.retrieve. A pure lookup: spends no credits, and works without a key. Model ids contain a slash, e.g. /api/v1/models/openai/gpt-image-2. This is a lookup and spends no credits. ```markdown ### Parameters - **id** (string, path, required): The model id (may contain slashes). ### Responses #### 200 - Success. Empty response body #### 401 - authentication_error: invalid API key (a request without a key is answered anonymously). authentication_error: invalid API key (a request without a key is answered anonymously). #### 429 - rate_limit_error: over 300 requests/minute for this key. rate_limit_error: over 300 requests/minute for this key. ### Example Usage ```bash curl -X GET "https://genmagic.co/api/v1/models/{id}" ``` ``` -------------------------------- ### GET /api/v1/benchmarks/{id} Source: https://genmagic.co/openapi.json One benchmark's full definition plus its model leaderboard ranked best-first, each score carrying its source and a link to the original. Answers 'which model is best at benchmark X'. A pure lookup: spends no credits. This is a lookup and spends no credits. ```markdown ### Parameters - **id** (string, path, required): The benchmark id, e.g. gpqa-diamond (see /api/v1/benchmarks). - **limit** (integer, query, optional): Max models to return (default 100, max 500). ### Responses #### 200 - Success. Empty response body #### 401 - authentication_error: missing or invalid API key. authentication_error: missing or invalid API key. #### 429 - rate_limit_error: over 300 requests/minute for this key. rate_limit_error: over 300 requests/minute for this key. ### Example Usage ```bash curl -X GET "https://genmagic.co/api/v1/benchmarks/{id}?limit=0" ``` ``` -------------------------------- ### GET /api/v1/models/changes Source: https://genmagic.co/openapi.json New models (by the catalog's listing date), price changes with the price before and after, retirements, returns, changed details, and benchmark scores that appeared or changed, per UTC day, with how many model pages each day touched: the data behind genmagic.co/models/changes. A pure lookup: spends no credits, and works without a key. This is a lookup and spends no credits. ```markdown ### Parameters - **days** (integer, query, optional): How many days back, 1 to 90 (default 7). ### Responses #### 200 - Success. Empty response body #### 401 - authentication_error: invalid API key (a request without a key is answered anonymously). authentication_error: invalid API key (a request without a key is answered anonymously). #### 429 - rate_limit_error: over 300 requests/minute for this key. rate_limit_error: over 300 requests/minute for this key. ### Example Usage ```bash curl -X GET "https://genmagic.co/api/v1/models/changes?days=0" ``` ``` -------------------------------- ### POST /api/v1/chat/completions Source: https://genmagic.co/openapi.json Point any OpenAI SDK at this base URL. Routes the messages to the selected model through GenMagic, billed against the key's real USD balance at the model's price in /api/v1/models (cached input and long-context prompts bill at the cache and tier prices listed there). The request body is forwarded to the model unchanged, so every parameter in the model's supported_parameters works as sent (temperature, tools, response_format, seed, ...). Streams with server-sent events when stream=true. When the key owner has Brand personalization on, a brand system message is prepended automatically. ```markdown ### Request Body **Content-Type:** application/json - **model** (string): Model id to use. Omit to use the text default. Call /api/v1/models to list ids. - **messages** (array (object)) (required): OpenAI-style messages array [{ role, content }]; supports multimodal content parts. - **stream** (boolean): Stream tokens as server-sent events. Defaults to false. - **reasoning_effort** (string): Thinking effort for a reasoning model, one of the model's capabilities.reasoning_efforts (for example low, medium, high). - **reasoning** (object): Object form of the thinking controls: { effort, enabled, max_tokens }. enabled: false is refused when the model's capabilities.reasoning_mandatory is true. ### Responses #### 200 - Success. Empty response body #### 401 - authentication_error: missing or invalid API key. authentication_error: missing or invalid API key. #### 402 - insufficient_quota: credit balance would go negative. insufficient_quota: credit balance would go negative. #### 429 - rate_limit_error: over 300 requests/minute for this key. rate_limit_error: over 300 requests/minute for this key. ### Example Usage ```bash curl -X POST "https://genmagic.co/api/v1/chat/completions" \ -H "Content-Type: application/json" \ -d '{ "model": "string", "messages": [ "value" ], "stream": "true", "reasoning_effort": "string", "reasoning": "value" }' ``` ``` -------------------------------- ### POST /api/v1/audio/music Source: https://genmagic.co/openapi.json GenMagic-native (OpenAI has no music endpoint). Returns raw audio bytes; a hosted URL rides X-Media-Url. Brand-steered in mood when personalization is on. ```markdown ### Request Body **Content-Type:** application/json - **prompt** (string) (required): Genre, mood, instruments, tempo. - **model** (string): Model id. Omit for the default. ### Responses #### 200 - Success. Empty response body #### 401 - authentication_error: missing or invalid API key. authentication_error: missing or invalid API key. #### 402 - insufficient_quota: credit balance would go negative. insufficient_quota: credit balance would go negative. #### 429 - rate_limit_error: over 300 requests/minute for this key. rate_limit_error: over 300 requests/minute for this key. ### Example Usage ```bash curl -X POST "https://genmagic.co/api/v1/audio/music" \ -H "Content-Type: application/json" \ -d '{ "prompt": "string", "model": "string" }' ``` ``` -------------------------------- ### POST /api/v1/images/edits Source: https://genmagic.co/openapi.json OpenAI's image edit call, so client.images.edit in the OpenAI SDKs and apps built on them work unchanged: upload the picture as the image file and describe the change in prompt. The same engine, price and response as /images/generations with a reference image. A JSON body with image as an https or data:image URL also works. Masks are refused (describe the change in the prompt instead). ```markdown ### Request Body **Content-Type:** multipart/form-data - **image** (string (binary)) (required): The picture to edit, as an uploaded file (the first one is used when several are sent). - **prompt** (string) (required): The edit to make. - **model** (string): Model id. Omit for the recommended default. - **size** (string (1024x1024|1792x1024|1024x1792)): Output size. ("1024x1024"|"1792x1024"|"1024x1792") - **response_format** (string (url|b64_json)): Return a hosted url (default) or base64. ("url"|"b64_json") - **n** (integer): Number of images (1-4). ### Responses #### 200 - Success. Empty response body #### 401 - authentication_error: missing or invalid API key. authentication_error: missing or invalid API key. #### 402 - insufficient_quota: credit balance would go negative. insufficient_quota: credit balance would go negative. #### 429 - rate_limit_error: over 300 requests/minute for this key. rate_limit_error: over 300 requests/minute for this key. ### Example Usage ```bash curl -X POST "https://genmagic.co/api/v1/images/edits" \ -H "Content-Type: application/json" \ -d '{ "image": "string", "prompt": "string", "model": "string", "size": "1024x1024", "response_format": "url", "n": "0" }' ``` ``` -------------------------------- ### POST /api/v1/agent/turn Source: https://genmagic.co/openapi.json The API face of the studio Agent. Send a conversation; it replies in character and returns a plan of on-brand assets to make. Planning is orchestration and is not billed (you then generate each asset via the matching endpoint). This is a lookup and spends no credits. ```markdown ### Request Body **Content-Type:** application/json - **messages** (array (object)) (required): Conversation [{ role, content }] ending in a user message. ### Responses #### 200 - Success. Empty response body #### 401 - authentication_error: missing or invalid API key. authentication_error: missing or invalid API key. #### 429 - rate_limit_error: over 300 requests/minute for this key. rate_limit_error: over 300 requests/minute for this key. ### Example Usage ```bash curl -X POST "https://genmagic.co/api/v1/agent/turn" \ -H "Content-Type: application/json" \ -d '{ "messages": [ "value" ] }' ``` ``` -------------------------------- ### POST /api/v1/audio/speech Source: https://genmagic.co/openapi.json Turn text into spoken audio. Returns raw audio bytes; a durable hosted URL rides the X-Media-Url header. Voiced verbatim (never brand-altered). ```markdown ### Request Body **Content-Type:** application/json - **input** (string) (required): The text to speak. - **model** (string): Model id. Omit for the default. - **voice** (string): Voice name (e.g. alloy). Defaults to a neutral voice. ### Responses #### 200 - Success. Empty response body #### 401 - authentication_error: missing or invalid API key. authentication_error: missing or invalid API key. #### 402 - insufficient_quota: credit balance would go negative. insufficient_quota: credit balance would go negative. #### 429 - rate_limit_error: over 300 requests/minute for this key. rate_limit_error: over 300 requests/minute for this key. ### Example Usage ```bash curl -X POST "https://genmagic.co/api/v1/audio/speech" \ -H "Content-Type: application/json" \ -d '{ "input": "string", "model": "string", "voice": "string" }' ``` ``` -------------------------------- ### POST /api/v1/images/generations Source: https://genmagic.co/openapi.json Generate an image from a prompt, or transform a reference image (image-to-image) by passing image. Set type=logo to steer as a brand mark. On-brand automatically when personalization is on. ```markdown ### Request Body **Content-Type:** application/json - **prompt** (string) (required): Description of the image (or the edit to make when image is given). - **model** (string): Model id. Omit for the recommended default. - **size** (string (1024x1024|1792x1024|1024x1792)): Output size. ("1024x1024"|"1792x1024"|"1024x1792") - **image** (string): Reference image to transform: an https URL or a data:image URL. - **type** (string (image|logo)): logo steers a brand mark; image is a picture. ("image"|"logo") - **response_format** (string (url|b64_json)): Return a hosted url (default) or base64. ("url"|"b64_json") - **n** (integer): Number of images (1-4). ### Responses #### 200 - Success. Empty response body #### 401 - authentication_error: missing or invalid API key. authentication_error: missing or invalid API key. #### 402 - insufficient_quota: credit balance would go negative. insufficient_quota: credit balance would go negative. #### 429 - rate_limit_error: over 300 requests/minute for this key. rate_limit_error: over 300 requests/minute for this key. ### Example Usage ```bash curl -X POST "https://genmagic.co/api/v1/images/generations" \ -H "Content-Type: application/json" \ -d '{ "prompt": "string", "model": "string", "size": "1024x1024", "image": "string", "type": "image", "response_format": "url", "n": "0" }' ``` ``` -------------------------------- ### POST /api/v1/text Source: https://genmagic.co/openapi.json GenMagic-native. Returns a finished artifact rather than raw model output: pass type to unlock the artifact's system prompt and, for svg/website, the brand's exact palette and typeface. Omit type for plain, voice-branded text. ```markdown ### Request Body **Content-Type:** application/json - **prompt** (string) (required): What to write or produce. - **type** (string (writing|code|svg|website)): The kind of artifact. Omit for plain text. ("writing"|"code"|"svg"|"website") - **model** (string): Model id. Omit for the type's default. - **system** (string): Extra steer applied after the brand system message. - **attachments** (array (object)): Files for the model to read: [{ name, mime, dataUrl }] (PDF, office, csv, text, image, audio). ### Responses #### 200 - Success. Empty response body #### 401 - authentication_error: missing or invalid API key. authentication_error: missing or invalid API key. #### 402 - insufficient_quota: credit balance would go negative. insufficient_quota: credit balance would go negative. #### 429 - rate_limit_error: over 300 requests/minute for this key. rate_limit_error: over 300 requests/minute for this key. ### Example Usage ```bash curl -X POST "https://genmagic.co/api/v1/text" \ -H "Content-Type: application/json" \ -d '{ "prompt": "string", "type": "writing", "model": "string", "system": "string", "attachments": [ "value" ] }' ``` ``` -------------------------------- ### Security: bearerAuth Source: https://genmagic.co/openapi.json GenMagic API key in the form gm_live_..., sent as Authorization: Bearer . Also accepted as x-api-key. ```markdown ## Security: bearerAuth **Description:** GenMagic API key in the form gm_live_..., sent as Authorization: Bearer . Also accepted as x-api-key. **Type:** http **Scheme:** bearer ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.