Generate media with AI agents

Generate images and videos from an agent

This guide gives Codex, Claude Code, and other shell-capable agents a deterministic Wizzx workflow. You provide one API key and a natural-language generation request; the agent validates a model-specific payload, submits one asynchronous task, saves the returned Task ID, and polls that task until it finishes. No SDK is required. All examples use https://api.wizzx.ai.

AI-readable documentation entrypoints

Give an agent the smallest useful source first. Use the index to discover a page, the Markdown page for readable model guidance, the OpenAPI document for exact fields, and /pricing for live availability and credit tiers.

Resource	Use it for
`llms.txt`	Compact, automatically updated documentation index. Start here when the model or page is unknown.
`llms-full.txt`	Full documentation context. Use only when the agent can load the whole site without crowding out the user’s request.
This guide as Markdown	Agent-readable version of this workflow without the web interface.
OpenAPI JSON	Machine-readable request, response, enum, and conditional parameter schemas.

llms.txt is a discovery index, not proof that a model is currently public or that an old price is still valid. Confirm availability and pricing with GET /pricing, then use OpenAPI and the selected model page to construct the payload.

Prerequisites

A Wizzx API key with enough credits.
An agent session allowed to make HTTPS requests.
Public HTTP(S) URLs for reference images. A local path or base64 value is not an image_urls value.

Image and video submission spends credits. A request such as “plan,” “draft,” or “estimate” does not authorize submission. A request such as “generate” or “create now” authorizes one submission. If a required choice can materially change the price, the agent must show the final model, parameters, and current estimate before asking for confirmation.

Give the key to the agent session

Keep the key in an environment variable instead of source code, a prompt transcript, or a committed .env file.

printf "Wizzx API key: "
read -rs WIZZX_API_KEY
printf "\n"
export WIZZX_API_KEY

Start Codex or Claude Code from the same shell. The agent should read WIZZX_API_KEY without printing it.

Copyable agent instruction

You can paste the following instruction into an agent or use it as the body of a reusable project skill.

Use the Wizzx API at https://api.wizzx.ai for this media request.

Security:
- Read the API key only from WIZZX_API_KEY.
- Never print, log, commit, or write the key to a file.

Execution contract:
1. Read https://docs.wizzx.ai/llms.txt to discover the relevant model page and https://docs.wizzx.ai/api-reference/openapi.json for its exact schema. Treat llms.txt as an index, not an availability or pricing source.
2. Read GET /pricing and confirm the selected model_key is currently public.
3. Read GET /api/v1/credits/balance with the Bearer key.
4. Build only fields allowed by the selected model schema. model_key belongs in the URL path, not the JSON body.
5. If the user asked only for a plan, payload preview, or cost estimate, stop before submission.
6. Submit exactly once with POST /api/v1/task/submit/{model_key}.
7. Require HTTP success, code == 0, and a non-empty data.task_id. Save and report that Task ID immediately.
8. Poll POST /api/v1/task/status with {"task_id":"..."} and the same Bearer key. Use backoff and honor retry_after on 429.
9. Continue for PENDING, QUEUED, or PROCESSING. Return result_urls for SUCCEEDED. Return error for FAILED. Stop and report REVIEW_REQUIRED without resubmitting.
10. If polling times out, return the Task ID so polling can resume. Never create a replacement task automatically.

Do not automatically retry a submit request after a network timeout or ambiguous 5xx response; it may create a second paid task. Ask the user before any second submission.

Endpoints

Purpose	Method and path	Authentication
Discover public models and current pricing	`GET /pricing`	None
Check the current credit balance	`GET /api/v1/credits/balance`	Bearer API key
Submit a generation	`POST /api/v1/task/submit/{model_key}`	Bearer API key
Query a task	`POST /api/v1/task/status`	Bearer API key

Use gpt-image-2 as the general image preset and veo3 as the general video preset only while each key appears in /pricing. If the user names another model, read that model’s API reference and do not reuse a preset schema.

Use /pricing for current credit tiers, then restrict selection to models published in these docs. Compatibility-only backend keys are not public choices. Do not keep a price copied from an old agent conversation.

Request schemas

These strict schemas prevent the agent from inventing fields. Omit optional fields that the user did not request. Reference images must be public HTTP(S) URLs.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "GPTImage2Request",
  "type": "object",
  "additionalProperties": false,
  "required": ["prompt"],
  "properties": {
    "prompt": {
      "type": "string",
      "minLength": 1,
      "description": "The gateway enforces a 32000-byte UTF-8 limit.",
      "x-wizzx-maxBytes": 32000
    },
    "image_urls": {
      "type": "array",
      "maxItems": 10,
      "items": {
        "type": "string",
        "format": "uri",
        "pattern": "^https?://"
      }
    },
    "size": {
      "type": "string",
      "enum": ["auto", "1024x1024", "1536x1024", "1024x1536"]
    },
    "quality": {
      "type": "string",
      "enum": ["auto", "low", "medium", "high"]
    },
    "output_format": {
      "type": "string",
      "enum": ["png", "jpeg", "webp"]
    }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Veo3Request",
  "type": "object",
  "additionalProperties": false,
  "required": ["prompt", "type"],
  "properties": {
    "prompt": {
      "type": "string",
      "minLength": 1
    },
    "type": {
      "type": "string",
      "enum": ["text-to-video", "image-to-video", "reference-to-video"]
    },
    "image_urls": {
      "type": "array",
      "minItems": 1,
      "maxItems": 3,
      "items": {
        "type": "string",
        "format": "uri",
        "pattern": "^https?://"
      }
    },
    "duration": {
      "type": "integer",
      "enum": [4, 6, 8],
      "default": 8
    },
    "resolution": {
      "type": "string",
      "enum": ["720p", "1080p", "4k"],
      "default": "720p"
    },
    "aspect_ratio": {
      "type": "string",
      "enum": ["16:9", "9:16", "Auto", "auto"],
      "default": "16:9"
    },
    "model": {
      "type": "string",
      "enum": ["veo3_fast", "veo3_lite", "veo3_quality"],
      "default": "veo3_fast"
    },
    "seeds": {
      "type": "integer",
      "minimum": 10000,
      "maximum": 99999
    },
    "enable_translation": {
      "type": "boolean"
    },
    "watermark": {
      "type": "string",
      "maxLength": 128
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {"type": {"const": "text-to-video"}},
        "required": ["type"]
      },
      "then": {
        "not": {"required": ["image_urls"]}
      }
    },
    {
      "if": {
        "properties": {"type": {"const": "image-to-video"}},
        "required": ["type"]
      },
      "then": {
        "required": ["image_urls"],
        "properties": {"image_urls": {"maxItems": 2}}
      }
    },
    {
      "if": {
        "properties": {"type": {"const": "reference-to-video"}},
        "required": ["type"]
      },
      "then": {
        "required": ["image_urls"],
        "properties": {
          "duration": {"const": 8}
        }
      }
    },
    {
      "if": {
        "properties": {"model": {"const": "veo3_quality"}},
        "required": ["model"]
      },
      "then": {
        "properties": {
          "duration": {"enum": [6, 8]},
          "type": {"enum": ["text-to-video", "image-to-video"]}
        }
      }
    }
  ]
}

The schemas above are the recommended general-purpose presets. Machine-readable request schemas for every publicly documented model are available in the API reference, including both Seedance models, Seedance 2.0 Mini, Kling AI, Kling v3, Kling v3 Omni, PixVerse V6, Grok Imagine Video 1.5, Gemini Omni Flash, Wan 2.6 Flash, Seedream 4/4.5, Seedream 5.0 Pro, all public Nano Banana variants, GPT Image 2, GPT Image 2.5, Qwen Image 2.0 / 2.0 Pro, and Suno.

Parameter construction rules

Rule	Agent behavior
Model placement	Put the model key in `/task/submit/{model_key}`; never add `model_key` to the body.
Optional values	Omit unknown values instead of sending `null`, an empty string, or a guessed enum.
Text-to-image	Use `gpt-image-2` without `image_urls`.
Image editing	Use `gpt-image-2` with 1–10 public URLs in `image_urls`.
Text-to-video	Set `type` to `text-to-video` and omit `image_urls`.
First/last-frame video	Use two images only when that model Schema explicitly allows it—currently Veo, Seedance 1.5 Pro, Seedance 2.0 Mini, Kling v3, Kling v3 Omni, and PixVerse V6 (5 or 8 seconds) image-to-video. Kling AI and Seedance Pro Fast accept exactly one image.
Veo reference video	Set `type` to `reference-to-video`, use 1–3 images and 8 seconds with `veo3_fast` or `veo3_lite` (16:9 or 9:16). `veo3_quality` does not support reference mode and accepts 6 or 8 seconds only.
Music	Use `suno`. A successful task usually returns two tracks; return every URL in `result_urls`, not just the first.
Unknown model	Open its API reference and construct a new payload; never mix fields from another model.

Image payload

{
  "prompt": "A cinematic product photo of an orange mechanical keyboard on a dark desk",
  "size": "1536x1024",
  "quality": "high",
  "output_format": "png"
}

Submit it to POST /api/v1/task/submit/gpt-image-2.

Video payload

{
  "prompt": "A paper boat travels through a neon city canal at night, slow cinematic camera movement",
  "type": "text-to-video",
  "duration": 6,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "model": "veo3_fast"
}

Submit it to POST /api/v1/task/submit/veo3.

Submit once and capture the Task ID

curl --fail-with-body --silent --show-error \
  -X POST "https://api.wizzx.ai/api/v1/task/submit/gpt-image-2" \
  -H "Authorization: Bearer $WIZZX_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "prompt": "A cinematic product photo of an orange mechanical keyboard on a dark desk",
    "size": "1536x1024",
    "quality": "high",
    "output_format": "png"
  }'

A successful submit response uses this envelope:

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "4bbbc9e0-8de8-4f35-a31e-8596c1a6d18a",
    "model_key": "gpt-image-2",
    "credits_deducted": 9
  },
  "request_id": "d54c66a8-0f0f-439c-bd3a-36f3fd275881"
}

The client must read data.task_id, not a provider task identifier. Treat credits_deducted as the amount reserved for this task.

Poll by Task ID

curl --fail-with-body --silent --show-error \
  -X POST "https://api.wizzx.ai/api/v1/task/status" \
  -H "Authorization: Bearer $WIZZX_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "task_id": "4bbbc9e0-8de8-4f35-a31e-8596c1a6d18a"
  }'

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "4bbbc9e0-8de8-4f35-a31e-8596c1a6d18a",
    "status": "SUCCEEDED",
    "result_urls": [
      "https://cdn.example.com/generated/image.png"
    ],
    "error": "",
    "credits_deducted": 9
  },
  "request_id": "499347b1-ff99-4ba2-a977-ad655431919d"
}

Status	Meaning	Agent action
`PENDING`	The durable task exists but is not queued yet.	Continue polling.
`QUEUED`	Credits are reserved and the task is waiting for a worker.	Continue polling.
`PROCESSING`	The provider is generating the media.	Continue polling with backoff.
`REVIEW_REQUIRED`	The provider outcome needs operator reconciliation.	Stop polling, report the Task ID, and do not resubmit.
`SUCCEEDED`	Generation finished.	Return every URL in `result_urls`.
`FAILED`	Generation failed.	Return `error`; do not reuse the old Task ID for a new submission.

A practical polling schedule is 5 seconds, then 10, 20, and at most 30 seconds between queries. If the agent reaches its time limit, the server task keeps running; return the Task ID and resume the status request later.

Error and retry rules

Errors use a different envelope:

{
  "error": {
    "message": "Human-readable explanation",
    "type": "invalid_request_error",
    "param": "type",
    "code": "invalid_parameter_value"
  },
  "request_id": "d54c66a8-0f0f-439c-bd3a-36f3fd275881"
}

HTTP status	Agent action
`400` / `422`	Fix the payload from `error.param` and `error.message`; do not retry unchanged.
`401`	Stop and ask for an active key. Never display the rejected key.
`402`	Stop and report insufficient credits.
`404` on status	Check the Task ID and account; tasks are isolated by owner.
`429`	Wait for `retry_after` or `X-Retry-After`, then retry the same status query.
`500` / `503` on status	Retry the same Task ID with backoff.
Network timeout or ambiguous `5xx` on submit	Do not submit again automatically; report the ambiguity and ask before a second paid attempt.

The run is complete only when the agent returns result URLs for SUCCEEDED, explains a terminal FAILED, reports REVIEW_REQUIRED, or hands back a Task ID that can be polled later. For more model-specific options, see Nano Banana 2, Seedance 1.5 Pro, and the API reference navigation.

Getting started

Agent integrations

Video Generation

Image Generation

Audio Generation

Generate media with AI agents

Generate images and videos from an agent

AI-readable documentation entrypoints

Prerequisites

Give the key to the agent session

Copyable agent instruction

Endpoints

Request schemas

Parameter construction rules

Image payload

Video payload

Submit once and capture the Task ID

Poll by Task ID

Error and retry rules

​Generate images and videos from an agent

​AI-readable documentation entrypoints

​Prerequisites

​Give the key to the agent session

​Copyable agent instruction

​Endpoints

​Request schemas

​Parameter construction rules

​Image payload

​Video payload

​Submit once and capture the Task ID

​Poll by Task ID

​Error and retry rules

Generate images and videos from an agent

AI-readable documentation entrypoints

Prerequisites

Give the key to the agent session

Copyable agent instruction

Endpoints

Request schemas

Parameter construction rules

Image payload

Video payload

Submit once and capture the Task ID

Poll by Task ID

Error and retry rules