Image Generation API

Image Generation

POST https://shark.ai/api/v1/images/generations

Generate images from text prompts. Returns Shark AI signed image URLs. Supports sync (default) and async modes — sync returns the result directly, async returns a task ID for polling.

Request Body

Parameters vary by model. Each image model defines its own parameter schema. Common fields:

Parameter	Type	Required	Description
model	string	✓	Model ID
prompt	string	✓	Text description of the image
async	boolean		Set `true` for async mode — returns 202 with task ID instead of waiting
timeout	integer		Async mode: max wait time in seconds (30-1800, default 300)
...			Additional model-specific parameters (size, quality, etc.)

See each model's documentation page for the full parameter schema.

Sync Response (200)

{
  "created": 1700000000,
  "data": [
    {
      "url": "https://cos.example.com/images/...signed..."
    }
  ],
  "usage": {
    "input_tokens": 14,
    "output_tokens": 1542,
    "total_tokens": 1556
  },
  "credit": 400
}

Field	Type	Description
created	integer	Unix timestamp
data	array	Array of generated images
data[].url	string	Short-lived signed image URL
usage	object	Optional provider token usage
credit	number	Cost (1 USD = 10,000 credit)

Async Mode

Set async: true to receive a 202 response with a task ID. Poll the task status endpoint until completion.

Async Response (202)

{
  "id": "task_abc123",
  "object": "image.generation.task",
  "status": "pending",
  "created": 1700000000,
  "timeout": 300,
  "polling_url": "https://shark.ai/api/v1/images/generations/task_abc123",
  "cancel_url": "https://shark.ai/api/v1/images/generations/task_abc123/cancel"
}

Poll Task Status

GET https://shark.ai/api/v1/images/generations/:id

Poll every 2-5 seconds until status is completed, failed, or cancelled.

Status	Description
pending	Waiting to start
running	Being generated
completed	Images ready
failed	Generation failed
cancelled	Cancelled by user

Completed Response

{
  "id": "task_abc123",
  "object": "image.generation.task",
  "status": "completed",
  "created": 1700000000,
  "timeout": 300,
  "result": {
    "created": 1700000000,
    "data": [
      {
        "url": "https://cos.example.com/images/...signed..."
      }
    ],
    "usage": {
      "input_tokens": 14,
      "output_tokens": 1542,
      "total_tokens": 1556
    },
    "credit": 400
  }
}

Failed Response

{
  "id": "task_abc123",
  "object": "image.generation.task",
  "status": "failed",
  "created": 1700000000,
  "timeout": 300,
  "error": {
    "message": "Image generation failed: provider timeout",
    "type": "generation_error"
  }
}

Cancel Task

POST https://shark.ai/api/v1/images/generations/:id/cancel

Cancel a pending task. Only tasks in pending status can be cancelled. Returns 409 if already started.

Code Examples

import requests

BASE = "https://shark.ai"
HEADERS = {"Authorization": "Bearer <api-key>", "Content-Type": "application/json"}

response = requests.post(f"{BASE}/api/v1/images/generations", headers=HEADERS, json={
    "model": "openai/gpt-image-2",
    "prompt": "A cute baby sea otter floating on calm water",
    "size": "1024x1024",
    "quality": "high",
    "n": 1,
}).json()
image = requests.get(response["data"][0]["url"])
with open("output.png", "wb") as f:
    f.write(image.content)

Notes

Image generation can take 10-180 seconds depending on the model
Returned image URLs are signed and short-lived; download and persist the file as soon as possible
Some models return multiple images per request (check the data array length)
Async mode is recommended for slow models (30s+). Set async: true and poll for the result.

See model list for available image models and their parameter schemas.