API Documentation

Build against the OpenOctopus API

OpenOctopus provides a unified API for image and video generation. Use one API key, one base URL, and public model slugs routed by the platform.

Overview

What the API gives you

Use a single OpenOctopus API key to submit image and video generation tasks through stable public model slugs.

Unified auth

One bearer token works across public OpenOctopus models.

Async tasks

Generation endpoints return a task id first, then you poll for the final result.

Routed models

You call public slugs while OpenOctopus handles upstream routing behind the scenes.

Authentication

Base URL and API key

All requests use the same base URL and a standard bearer token in the Authorization header.

Base URL

https://alluring-reflection-production-eafd.up.railway.app

Header

Authorization: Bearer ooq_your_api_key

Create API keys from the dashboard after signing in. Save the full key when it is created because the full value is only shown once.

Quickstart

From account to first request

This is the shortest path from a new account to a working API call.

Create or access your workspace, then open the dashboard.

Create an API key

Generate a workspace API key from the dashboard and save it immediately. The full key is only shown once.

Choose a public model

Use the OpenOctopus public model slug that you want to call, such as openoctopus/seedream-4.5.

Send a request

Call a generation endpoint with your API key in the Authorization header.

Poll task status

Generation requests are asynchronous. Poll the task endpoint until the request finishes.

Endpoints

Public API surface

These are the customer-facing endpoints currently reflected by the app and gateway worker.

GET

/v1/models

List currently active public models and their routed upstream providers.

POST

/v1/images/generations

Queue an image generation task.

POST

/v1/videos/generations

Queue a video generation task.

GET

/v1/tasks/:id

Fetch the current status and output payload for a task.

Examples

Common request patterns

Start with the model list endpoint, then send generation requests, and finally poll the task status endpoint.

List models

Fetch the current public model catalog before hard-coding model names in your own app.

curl https://alluring-reflection-production-eafd.up.railway.app/v1/models

Image generation

Submit an image generation task and receive a queued task id in the first response.

curl -X POST https://alluring-reflection-production-eafd.up.railway.app/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ooq_your_api_key" \
  -d '{
    "model": "openoctopus/seedream-4.5",
    "prompt": "a premium octopus mascot, orange and black, clean background"
  }'

Video generation

Video requests follow the same async lifecycle through the dedicated video endpoint.

curl -X POST https://alluring-reflection-production-eafd.up.railway.app/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ooq_your_api_key" \
  -d '{
    "model": "openoctopus/kling-v2.1",
    "prompt": "cinematic aerial shot of a neon harbor at night",
    "input": {
      "durationSeconds": 5,
      "aspectRatio": "16:9"
    }
  }'

JavaScript example

Any server-side JavaScript runtime can call the API over normal HTTP.

const response = await fetch("https://alluring-reflection-production-eafd.up.railway.app/v1/images/generations", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer " + process.env.OPENOCTOPUS_API_KEY,
  },
  body: JSON.stringify({
    model: "openoctopus/seedream-4.5",
    prompt: "a premium octopus mascot, orange and black, clean background",
    input: {
      size: "1024x1024"
    }
  }),
});

const task = await response.json();
console.log(task);

Responses

Queued task and final result

Generation endpoints are asynchronous. Expect a queued task response first, then poll until you receive a terminal result.

Initial queued response

{
  "id": "7c47ef1f-5e69-43d2-9f66-b4a1f2f0e7fd",
  "status": "queued"
}

Task status polling

Poll until the task moves from queued or processing to a terminal state.

curl https://alluring-reflection-production-eafd.up.railway.app/v1/tasks/task_id_from_previous_response \
  -H "Authorization: Bearer ooq_your_api_key"

Example completed response

{
  "id": "7c47ef1f-5e69-43d2-9f66-b4a1f2f0e7fd",
  "status": "succeeded",
  "capability": "image_generation",
  "public_model_slug": "openoctopus/seedream-4.5",
  "output_payload": {
    "assets": [
      {
        "url": "https://cdn.openoctopus.ai/generated/example.png"
      }
    ]
  },
  "error_code": null,
  "error_message": null,
  "created_at": "2026-04-12T08:00:00.000Z",
  "completed_at": "2026-04-12T08:00:09.000Z"
}

Request body fields

model is required and must be a public OpenOctopus model slug.

prompt is optional in the request schema, but many upstream models still expect it.

input is a free-form object for model-specific parameters such as size, aspect ratio, duration, or seed.

Errors

Structured error responses

Authentication failures and request validation failures use a simple error envelope with a machine-readable code.

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or inactive API key"
  }
}